Elasticsearch 9.0 shipped in early 2025, and the upgrade from 8.x introduces fewer disruptive changes than the 7-to-8 jump. There is no repeat of the security-by-default shock or the mapping types removal. The breaking changes center on removing long-deprecated settings, tightening defaults, and switching internal security infrastructure from the Java SecurityManager to a new Entitlements system. Most clusters that kept up with deprecation warnings during 8.x will have a straightforward migration.
You must be on 8.19.x before upgrading to 9.0. There is no supported path from 8.17 or earlier directly to 9.x. Elastic requires the last minor version of the previous major as the stepping stone. Run the Upgrade Assistant in Kibana 8.19 and address every critical issue before proceeding.
Pre-Upgrade Readiness Checks
The _migration/deprecations API is your primary tool for identifying blockers. Call it against your 8.19.x cluster and review every item marked as critical - these will prevent a 9.x node from starting or cause runtime failures.
GET /_migration/deprecations
The Kibana Upgrade Assistant wraps this API in a UI with guided resolution steps. It also flags indices created before 8.0.0 that may need reindexing. If your cluster still holds indices originally created on 7.x that were never reindexed, resolve those now.
Take a snapshot of the entire cluster before starting. This is your rollback path. A major version upgrade changes the data directory format, so you cannot downgrade by reinstalling 8.x binaries. Your only recovery option is restoring from the snapshot into a fresh 8.x cluster. Test the restore procedure in staging before touching production.
Breaking Changes in Elasticsearch 9
The most visible change is the permanent switch from the Java SecurityManager to Entitlements. The SecurityManager was deprecated in JDK 17 and disabled in JDK 24. Elasticsearch 9 replaces it with its own Entitlements system for plugin sandboxing. If you maintain custom plugins that relied on SecurityManager permission grants, they need reworking.
Legacy index templates (the v1 _template API) are removed. Migrate from PUT _template/my_template to composable index templates (PUT _index_template/my_template) before upgrading. Check for existing legacy templates with GET _template and convert each one.
Frozen indices created with the old freeze API must be unfrozen before upgrading. The frozen tier using searchable snapshots remains, but the legacy _freeze endpoint is gone. Metadata field definitions no longer accept type, fields, copy_to, and boost parameters - remove these from mappings on fields like _id or _source.
The cluster.routing.allocation.balance.threshold no longer accepts values below 1.0. TLSv1.1 is disabled by default - audit client TLS configurations. The discovery.type setting only accepts multi-node and single-node; other values cause startup failures.
Rolling Upgrade Procedure
A rolling upgrade gives you zero downtime. Upgrade non-master-eligible nodes first, then data nodes by tier (frozen, cold, warm, hot), and master-eligible nodes last.
For each node:
# 1. Disable shard allocation
PUT _cluster/settings
{ "persistent": { "cluster.routing.allocation.enable": "primaries" } }
# 2. Flush
POST _flush
# 3. Stop the node, install 9.x packages, start the node
# 4. Re-enable allocation
PUT _cluster/settings
{ "persistent": { "cluster.routing.allocation.enable": null } }
# 5. Wait for green before proceeding to the next node
GET _cluster/health?wait_for_status=green&timeout=5m
The mixed-version state during the upgrade is supported but keep it brief. New 9.x-only features will not be available until every node is upgraded. A regular flush before stopping each node is sufficient - synced flush was removed in 8.x, and Elasticsearch uses sequence numbers for recovery.
Plugin and Client Compatibility
Check every installed plugin against the 9.x compatibility matrix before upgrading. Plugins compiled for 8.x will not load on 9.x. For Elastic-maintained plugins (analysis-icu, repository-s3, etc.), matching versions ship alongside each Elasticsearch release. For community plugins, verify a 9.x-compatible release exists.
Client libraries require version alignment. The major version of the client should match the server. The Java API Client, Python elasticsearch-py, and other official clients all have 9.x releases. Using an 8.x client against a 9.x cluster may work via wire compatibility mode for basic operations, but you risk hitting removed behaviors. Update clients shortly after the cluster upgrade.
For applications using the low-level REST client directly, most well-formed 8.x requests work on 9.x without modification. The exceptions are removed endpoints like the legacy template API or frozen index API.
Common Post-Upgrade Issues
Elasticsearch 9.x reads indices created in 8.x without issues. Indices originally created in 7.x and upgraded through 8.x should also work, but indices tracing back to 6.x creation will not open. Run GET /my-index/_settings?filter_path=**.version.created on any suspect indices.
Changed defaults cause subtle behavioral shifts. The cluster.routing.allocation.balance.threshold minimum of 1.0 catches clusters that tuned this to a low value for aggressive rebalancing. If your cluster stops rebalancing after the upgrade, check whether this setting was corrected.
LogsDB mode is now conditionally enabled by default for data streams matching logs-*. Custom data streams with that naming convention may pick up LogsDB behavior (synthetic source, sort-on-ingest) unexpectedly. Review your data stream templates and override the default if needed. Monitor cluster health closely for 24-48 hours after completing the upgrade, and watch for new deprecation warnings - these signal features that will be removed in 10.x.
