The Elasticsearch Deprecation API surfaces deprecated settings, mappings, and features that will break or change behavior in the next major version. Running this API before an upgrade is the fastest way to get a concrete list of what needs to change across your cluster, nodes, and indices.
The _migration/deprecations Endpoint
The primary endpoint is GET /_migration/deprecations. It returns deprecation warnings organized into four categories: cluster_settings, node_settings, index_settings, and ml_settings. Each entry includes a severity level (warning or critical), a human-readable message, a url pointing to the relevant documentation, and an optional details field with specifics like the setting name or index involved.
You can also scope the request to a specific index with GET /<index_name>/_migration/deprecations, which filters the response to only include deprecation warnings relevant to that index. This is useful when you manage hundreds of indices and want to tackle them one at a time.
GET /_migration/deprecations
// Response structure:
{
"cluster_settings": [ { "level": "critical", "message": "...", "url": "...", "details": "..." } ],
"node_settings": [ ... ],
"index_settings": { "my-index": [ ... ] },
"ml_settings": [ ... ]
}
A critical-level entry means the upgrade will fail or the feature will stop working unless you take action. Warning-level entries indicate features that still function but will be removed in a later release.
Deprecation Logs, Headers, and Filtering
Beyond the dedicated API, Elasticsearch reports deprecation usage through two additional channels. First, any REST API request that triggers deprecated functionality returns a Warning HTTP response header. This header contains a text description of the deprecated feature used. Client libraries and HTTP tools can parse these headers to flag deprecated usage in application code or automated tests.
Second, Elasticsearch writes deprecation events to a dedicated log file, typically elasticsearch_deprecation.json in the logs directory. Each entry is a JSON object containing the timestamp, log level (CRITICAL or WARN), the component that triggered the deprecation, cluster metadata, and the deprecation message itself. These logs are deduplicated by a combination of the deprecated feature key and the X-Opaque-Id header value, so repeated calls to the same deprecated API from the same client won't flood the log file. You can set the X-Opaque-Id HTTP header on your requests to tag them with an identifier - a service name, a pipeline ID, or a user label. This value appears in the x-opaque-id field of the deprecation JSON log, making it straightforward to trace which application or script is triggering deprecated behavior.
A large cluster can produce hundreds of deprecation entries. To work through them systematically, start by separating critical entries from warnings. Critical entries block upgrades; warnings give you runway but still need attention. Group the output by category: cluster-level settings are typically a short list that one person can address, node-level settings may require rolling restarts to apply configuration file changes, and index-level deprecations often span many indices and benefit from scripted bulk updates using the index settings API or reindex operations. For the log file, parse elasticsearch_deprecation.json with jq to extract unique messages, count occurrences, or filter by x-opaque-id. Pipe the output into a spreadsheet or issue tracker to build a ranked work list.
Using the Kibana Upgrade Assistant
Kibana includes an Upgrade Assistant that wraps the Deprecation API with a graphical interface. It pulls data from GET /_migration/deprecations and the Kibana deprecations API, then displays cluster, index, and Kibana-specific issues in categorized tabs. For some deprecations - like removed cluster or index settings - the Upgrade Assistant offers one-click resolution that calls the appropriate settings API to remove or update the value.
The assistant also tracks a "deprecation logging checkpoint" timestamp. After you address a batch of issues, you can reset the checkpoint so only new deprecation log entries appear. This keeps the interface clean as you iterate through fixes. For index-level changes that require reindexing, the assistant provides an API to start, monitor, and cancel reindex operations directly from the UI.
Common Deprecation Categories
Most deprecation warnings fall into a few recurring buckets. Removed settings are the most common - a setting that existed in the current version is gone in the next. The fix is usually to remove the setting from elasticsearch.yml or from the cluster/index dynamic settings. Changed defaults are subtler: a setting still exists, but its default value has changed. You need to decide whether to explicitly set the old value or adopt the new default.
Deprecated mapping types appeared heavily during the 6.x to 7.x migration when multi-type indices were removed. In later versions, similar patterns show up with deprecated field type parameters or analyzer configurations. Deprecated API endpoints also appear - for example, the _xpack prefix was dropped from many endpoints, and older clients still hitting those paths will generate deprecation warnings.
Legacy index templates (the _template API) are deprecated in favor of composable index templates (_index_template). If your cluster still uses legacy templates, the deprecation API flags each one.
Building an Upgrade Readiness Checklist
Convert the deprecation output into an actionable checklist. For each entry, record the category, severity, affected resource (cluster, node name, or index name), the specific message, and the remediation step. Assign owners where applicable - cluster settings go to the platform team, index mappings go to the team that owns the data pipeline.
Run the deprecation API again after each batch of fixes to confirm entries disappear. Automate this with a script that calls the API, counts remaining critical and warning entries, and fails a CI check if any critical issues remain. This approach lets you gate upgrade approval on a clean deprecation report.
Test the upgrade on a non-production cluster after clearing all critical deprecations. Some deprecations only manifest at runtime under specific query patterns, so run your integration test suite against the upgraded test cluster before proceeding to production.
