Elasticsearch Error: Index creation fails due to invalid settings - Common Causes & Fixes

illegal_argument_exception: unknown setting [<setting>] or illegal_argument_exception: Failed to parse value [<value>] for setting [<setting>] is returned when PUT /<index> (or an ILM/templated creation) is called with a setting that the running Elasticsearch version does not recognize, a value of the wrong type, or a combination that violates index-level invariants. The index is not created; the cluster state stays unchanged.

What This Error Means

Elasticsearch validates index settings at the moment an index is created. The settings allowed depend on the running version, the loaded plugins, the active license, and the static vs dynamic classification of each setting. Unknown setting names, malformed values, deprecated names with no current alias, or static settings sent to the dynamic settings API all result in a 400 Bad Request with illegal_argument_exception.

The error is purely client-side from the cluster's perspective - no shards are allocated, no segments are written.

Common Causes

1. Setting name does not exist in the running version (typo, deprecated, or x-pack-only). How to confirm: the error names the unknown setting; look it up in index modules reference for the running version.
2. Static setting (e.g., number_of_shards) sent to a running index via _settings API. How to confirm: error says "Can't update non dynamic setting"; static settings can only be set at index creation.
3. Index template applies an invalid setting at auto-creation time. How to confirm: GET _index_template/<name> and check the settings block; reproduce with POST _index_template/_simulate_index/<index-name>.
4. Setting requires a license tier you do not have (e.g., searchable snapshots, ILM with frozen tier on basic). How to confirm: error message includes "license"; check GET _license.
5. Value of wrong type or out of range (e.g., "number_of_replicas": "-1"). How to confirm: error names the parsing failure with the rejected value.
6. include_type_name set on Elasticsearch 8+ (removed). How to confirm: error rejects the parameter; the mapping types feature was removed in 8.0.

How to Fix Invalid Index Settings

1. Read the exact error. Add ?error_trace=true to surface the full stack:

   curl -X PUT 'https://es:9200/my-index?error_trace=true' \
     -H 'Content-Type: application/json' -d '{...}'
   

2. Simulate the resolved settings before creating:

   POST _index_template/_simulate_index/my-index-2026.01.01
   

   The response shows the final merged settings and mappings from all matching templates.

3. Use the minimum valid index body to isolate the failing setting:

   PUT /my-index
   {
     "settings": { "number_of_shards": 3, "number_of_replicas": 1 }
   }
   

   Add settings back one at a time until the error reappears.

4. For typos and deprecated names, consult the version's docs. Many index.translog.*, index.merge.*, and index.codec settings have moved or been renamed across major versions.

5. For "can't update non dynamic setting" on existing indices, create a new index with the desired static settings and reindex:

   PUT /my-index-v2 { "settings": { "number_of_shards": 6 } }
   POST _reindex { "source": {"index":"my-index"}, "dest": {"index":"my-index-v2"} }
   

6. For licensed-feature errors, either upgrade the license or remove the setting. GET _license reports the active tier.

7. For 8.x clients calling 7.x APIs (or vice versa), align client library version to the cluster version per the compatibility matrix.

Resolve Invalid Index Settings Automatically with Pulse

Pulse is an AI DBA for Elasticsearch and OpenSearch. When illegal_argument_exception: unknown setting [<setting>] or Failed to parse value [<value>] for setting [<setting>] blocks an index creation, Pulse:

• Parses the rejected setting name and value from the 400 response, then traces the source: an explicit PUT /<index> call, a matching _index_template (resolved via _simulate_index/<name>), a component_template referenced by composition, or an ILM-managed rollover
• Identifies which of the six causes applies: unknown setting name for the running version, static setting sent to _settings on a running index, template-injected invalid setting, license tier mismatch flagged by GET _license, value type/range violation, or a removed parameter like include_type_name on Elasticsearch 8+
• Generates the exact remediation: the corrected setting name with the current version's docs reference, the _simulate_index payload to validate the fix before retry, or the PUT /my-index-v2 { number_of_shards: N } plus reindex plan for static-setting changes on existing indices
• Applies template and component-template corrections with operator approval; leaves reindex workflows and license upgrades as one-click PRs

Pulse continuously watches for failed index creations from ILM rollover, alerting on misconfigured templates before the next backing index is auto-created and fails.

Start a free trial to connect your cluster.

Frequently Asked Questions

Q: Can I change index settings after the index is created?
A: Dynamic settings (replicas, refresh interval, slowlog thresholds) can be changed at any time via PUT /<index>/_settings. Static settings (number_of_shards, codec) can only be set at creation; changing them requires a new index plus reindex or Split/Shrink.

Q: How do I know which settings are dynamic vs static?
A: The Elasticsearch index modules reference marks each setting as "static" or "dynamic". Static settings appear in the index settings response under index.* with an index.creation_date lock.

Q: What changed about index creation in Elasticsearch 8.0?
A: Mapping types were fully removed in 8.0; the include_type_name parameter is no longer accepted. Several xpack.* settings moved into core. Some legacy index.translog.flush_threshold_size syntax was tightened.

Q: Why does my index template create indices with the wrong shard count?
A: Multiple templates can match an index name; the highest-priority template wins. Use _index_template/_simulate_index/<name> to see which template actually applies. Newer composable templates take precedence over legacy templates if both exist.

Q: Can a missing license cause "invalid settings"?
A: Yes. Settings tied to platinum/enterprise features (searchable snapshots, frozen tier, ILM with frozen actions) are rejected on basic license. The error message names the licensed setting.

Q: How do I dry-run an index creation?
A: Use POST _index_template/_simulate_index/<name> to see the resolved settings and mappings without creating the index. There is no dry_run flag on the create-index API itself.

Q: What's the fastest way to diagnose invalid index settings in production?
A: Pulse, the AI DBA for Elasticsearch and OpenSearch, parses the illegal_argument_exception response, traces the rejected setting back to the explicit call, matching index template, or ILM policy, and names the correction against the running version's docs. It applies template and component-template fixes after operator approval and watches future ILM rollovers so the same misconfiguration cannot fail again silently.

Related Reading

• Elasticsearch create index with mapping: correct shape of a create-index request.
• Elasticsearch IllegalArgumentException: mapper conflicts: the mapping-side counterpart.
• Elasticsearch settings reference: overview of cluster and index settings.
• Elasticsearch ElasticsearchIllegalArgumentException: broader illegal-argument errors.
• Elasticsearch monitoring: proactive detection of index creation failures.