index.mapping.total_fields.limit caps the number of fields, multi-fields, and metadata fields that an Elasticsearch index can hold in its mapping. The default is 1000. The setting exists to prevent "mapping explosion" - the runaway growth of mappings (and the heap they consume) that happens when dynamic mapping is left on and ingest documents keep introducing new keys. When the limit is reached, attempts to add new fields fail with Limit of total fields [N] has been exceeded, blocking further document writes that carry unknown fields.
How the total_fields Limit Works
Every field in a mapping - top-level scalars, object subfields, multi-fields like text plus keyword, runtime fields, and inherited metadata fields - counts as one entry against the limit. A text field with a keyword multi-field counts as two. A nested object with five subfields counts as six (one for the nested type plus five). Flattened fields are a deliberate exception: they count as a single entry regardless of how many leaves the indexed objects contain, which is why flattened is the standard escape valve when ingested JSON has arbitrary keys.
Hitting the limit produces a hard write failure for any document that would add a new field. Existing documents continue to be searchable and existing fields continue to ingest. The default of 1000 has been stable since the limit was introduced in Elasticsearch 5.x; it has not been raised in newer versions.
PUT /my-index/_settings
{
"index.mapping.total_fields.limit": 2000
}
GET /my-index/_mapping/field/*
The Get Mapping API with field/* returns every mapped field; combine with a jq/script count to see your current usage.
Settings That Interact With total_fields.limit
| Setting | Default | What it caps |
|---|---|---|
index.mapping.total_fields.limit |
1000 | Total mapped fields per index. |
index.mapping.depth.limit |
20 | Maximum object nesting depth. |
index.mapping.nested_fields.limit |
50 | Number of distinct nested mappings per index. |
index.mapping.nested_objects.limit |
10000 | Total nested objects per document. |
index.mapping.field_name_length.limit |
Long.MAX_VALUE | Maximum field name length. |
index.mapping.dimension_fields.limit |
21 (8.x); 32 (9.x) | TSDB dimension field cap. |
All are index-level settings, dynamically updatable via PUT /<index>/_settings. They apply only to the targeted index, not the cluster. For new indices, set them in the index template so newly created backing indices inherit the right ceilings.
Common Pitfalls With total_fields.limit
- Raising the limit instead of fixing the root cause. If you keep ingesting documents with new keys, raising the limit only delays the failure and grows mapping memory linearly with field count.
- Leaving
dynamic: trueon a production index that receives third-party payloads. The right setting for ingest from untrusted producers isdynamic: strict(reject unknown fields) ordynamic: false(accept but don't map) paired with explicit field declarations. - Forgetting that multi-fields count. A mapping declared with
text+keywordmulti-field doubles your field budget. - Using
objectfor dynamic JSON sub-trees when `flattened` would do. Flattened sub-trees count as one, object sub-trees count every leaf. - Setting different limits on indices in the same template. Newly rolled backing indices inherit template settings; check that index settings written via
_settingsaren't masking template values.
Resolving and Preventing Mapping Explosion
The durable fix when you hit the limit is rarely "raise it." The right sequence is: identify the field-generating ingest path, switch the affected index to dynamic: strict or dynamic: false, curate explicit mappings via Put Mapping for the fields you actually query, and migrate dynamic sub-trees to flattened. Then, if you still need a higher cap, raise the limit with the new design in mind.
Prevent Mapping Explosion with Pulse
Pulse is an AI DBA for Elasticsearch and OpenSearch that tracks index.mapping.total_fields.limit (default 1000) and related caps - depth.limit (20), nested_fields.limit (50), nested_objects.limit (10000), dimension_fields.limit (21 in 8.x, 32 in 9.x) - against actual mapping growth, flagging:
- Drift between template intent and per-index overrides applied via
PUT /<index>/_settings - Settings that are unsafe for your workload (e.g.
total_fields.limitraised to 2000 to "make the error go away" whiledynamic: truekeeps generating new fields; anobjectsub-tree mapping every dynamic JSON key where aflattenedfield would count as one) - The downstream operational impact: cluster state size, master GC pressure, and the rate of
Limit of total fields [N] has been exceededwrite failures per index
When a write failure does occur, Pulse identifies the ingest source adding the new fields and proposes the mapping change - typically dynamic: strict plus a flattened field for the dynamic sub-tree - that resolves it without raising the limit.
Frequently Asked Questions
Q: What is the default value of index.mapping.total_fields.limit in Elasticsearch?
A: 1000. This default has been stable since the setting was introduced in Elasticsearch 5.x and has not been increased in 7.x, 8.x, or 9.x. Each top-level field, object subfield, multi-field, and inherited metadata field counts as one entry.
Q: What happens when an index reaches index.mapping.total_fields.limit?
A: Attempts to index documents that would introduce a new field fail with Limit of total fields [N] has been exceeded. Existing fields and existing documents are unaffected. Reads continue to work normally; only writes that would extend the mapping are blocked. See the mapping limit exceeded error for the full failure mode.
Q: Should I raise index.mapping.total_fields.limit or change my mapping?
A: Almost always change the mapping. Raising the limit grows the per-index mapping memory footprint and slows mapping operations linearly with field count. The right pattern is dynamic: strict for known schemas and flattened fields for sub-trees with arbitrary keys.
Q: How do I count the current number of fields in an index?
A: Call GET /<index>/_mapping and traverse the response, counting every field, multi-field, and metadata entry. The Field Capabilities API (GET /<index>/_field_caps?fields=*) is faster for the count and avoids parsing the full mapping structure.
Q: Does increasing index.mapping.total_fields.limit affect cluster performance?
A: Yes, indirectly. Each mapped field carries metadata that lives in the cluster state. Very large mappings (thousands of fields per index across hundreds of indices) make cluster state updates expensive and slow down master-node operations. Aim for the lowest limit that fits your real schema.
Q: Can I set total_fields.limit at the cluster level?
A: No. It is an index-level setting only. Apply it via index templates to make it consistent across newly created indices, or update existing indices individually with PUT /<index>/_settings.
Q: What's the best tool to prevent Elasticsearch mapping explosion?
A: Pulse is built for this. It is an AI DBA for Elasticsearch and OpenSearch that tracks per-index field count growth against index.mapping.total_fields.limit, identifies the ingest source adding new fields, and proposes a dynamic: strict plus flattened field redesign that resolves the failure without raising the limit and growing cluster state.
Related Reading
- Elasticsearch mapping limit exceeded error: the write failure when the cap is hit and how to recover.
- Elasticsearch too many fields / mapping explosion: the underlying anti-pattern.
- Elasticsearch flattened field data type: the right tool for dynamic JSON sub-trees.
- Elasticsearch create index with mapping: declare strict mappings up front.
- Elasticsearch add field to mapping: curated field additions via Put Mapping.
- Elasticsearch error: too many nested objects: the related nested-object limit and how it interacts.
