Elasticsearch Error: Too Many Nested Objects in a Single Document - Common Causes & Fixes

The error The number of nested documents has exceeded the allowed limit of [10000] is thrown when an incoming document contains more nested objects (across all nested fields combined) than index.mapping.nested_objects.limit permits. The default is 10,000 per parent document. The error happens at index time; the document is rejected entirely. The limit exists because every nested object becomes a hidden Lucene sub-document, and a single parent with millions of nested children would crater the cluster's indexing throughput, segment merge time, and query latency.

What This Error Means

Elasticsearch indexes a nested field by emitting one hidden Lucene document per array element. A document with 50 nested children produces 51 Lucene documents (one parent + 50 nested). index.mapping.nested_objects.limit caps the total nested-document count per parent across every nested field in the mapping, so a document with two nested fields each carrying 6,000 entries fails the same way as a single nested field with 12,000 entries.

The check runs in the ingest path and produces:

The number of nested documents has exceeded the allowed limit of [10000].
This limit can be set by changing the [index.mapping.nested_objects.limit] index level setting.

The document is not partially indexed. Other documents in the same bulk request succeed or fail individually based on their own nested counts.

Common Causes

1. A genuinely large array in one document - thousands of line items, audit events, log entries crammed into one parent.
2. A data-model mistake where what should be many small documents has been collapsed into one document with a big nested array.
3. Migration from a denormalized source that did not have a per-document size limit.
4. A nested-within-nested mapping where the total count multiplies (5 outer entries each containing 3 nested children = 5 + 15 = 20, escalating fast).
5. The index has the default limit (10,000) but the workload was designed against an older or higher limit.

How to Fix the Too Many Nested Objects Error

1. Identify which field is over-budget. Pull a failing document and count nested entries per nested path:

   GET <index>/_doc/<id>
   # then count entries under each nested field
   

2. Decide whether the document should be split. If the nested array represents independent entities (orders containing thousands of events), reshape one parent into many child documents in a separate index. This is almost always the right answer.
3. Switch to flattened if you don't need correlated inner queries. A `flattened` field has no per-document cap on inner entries and counts as one mapped field. The trade-off is no analyzed search and no per-leaf numeric typing.
4. Raise index.mapping.nested_objects.limit only as a stopgap. Each nested object adds Lucene overhead. Raising the limit to 50,000 or 100,000 makes the error go away but slows indexing and queries proportionally.

   PUT <index>/_settings
   { "index.mapping.nested_objects.limit": 50000 }
   

5. Reindex with the new model. Whether you split documents or switch to flattened, the existing data has to be reindexed into the new shape. Use the Reindex API with a script that performs the split.

Resolve Too Many Nested Objects Automatically with Pulse

Pulse is an AI DBA for Elasticsearch and OpenSearch. When The number of nested documents has exceeded the allowed limit of [10000] rejects an index request, Pulse:

• Captures the failing document IDs from indexing exception logs and the _bulk response, sums nested-object counts per nested path across each rejected document, reads index.mapping.nested_objects.limit and index.mapping.nested_fields.limit from the index settings, and inspects the mapping for nested fields nested inside other nested fields (where counts multiply)
• Classifies whether the failure is an outlier (one document with abnormally many entries) or a steady-state workload consistently above budget, identifying which of the five causes applies: genuinely large array, denormalized data model that should be many documents, migration from a source without per-document size limits, nested-within-nested multiplication, or workload designed against an older/higher limit
• Generates the exact remediation: the PUT <index>/_settings { "index.mapping.nested_objects.limit": 50000 } stopgap (with the linear-overhead cost called out), the `flattened` field migration for cases without correlated inner queries, or the POST _reindex plan to split one parent into many child documents in a separate index
• Applies dynamic limit increases with operator approval (and an explicit cost note); leaves data-model splits and flattened migrations as one-click PRs because they change query shape

Pulse surfaces indices approaching the nested-object threshold continuously, so the per-document count distribution is visible before the first rejection hits production traffic.

Start a free trial to connect your cluster.

Frequently Asked Questions

Q: What is the default value of index.mapping.nested_objects.limit?
A: 10,000 nested objects per parent document, summed across every nested field in the mapping. This default applies to all versions from 7.x onward. Older references to 50 are about index.mapping.nested_fields.limit (number of nested mappings), which is a separate setting.

Q: How is index.mapping.nested_objects.limit different from nested_fields.limit?
A: nested_objects.limit (default 10,000) caps the count of nested objects in one document at index time. nested_fields.limit (default 50) caps the number of distinct nested field mappings allowed on the index. Both are index-level settings, updatable via PUT /<index>/_settings.

Q: Should I raise the nested_objects.limit to fix the error?
A: Only as a short-term workaround. The limit exists because nested-object overhead scales linearly with count: indexing throughput, merge cost, and nested-query latency all degrade. The durable fix is usually to split documents, denormalize to a child index, or switch to flattened if correlated inner queries aren't needed.

Q: Can I check the current nested object count of a document before indexing?
A: Not from inside Elasticsearch. Validate at the producer: walk the JSON, sum array lengths under nested paths, and reject or split before sending the document. The Update API and Reindex API let you split existing documents server-side via Painless scripts.

Q: Is this error related to the total fields limit?
A: No. `index.mapping.total_fields.limit` counts mapped fields, an index-level cap. nested_objects.limit counts nested sub-documents per parent, a document-level cap. Different failure modes with different fixes.

Q: Does increasing nested_objects.limit require a reindex?
A: No. The setting is dynamic and applies on the next ingest. Existing documents already at or below the new limit are unaffected. Documents that previously failed must be re-sent by the producer.

Q: What's the fastest way to diagnose "Too many nested objects" in production?
A: Pulse, the AI DBA for Elasticsearch and OpenSearch, captures the failing document IDs, sums nested-object counts per nested path, and classifies whether the cause is one outlier or a workload consistently above budget. It proposes the right fix - document split, flattened migration, or measured limit increase - with the operational cost surfaced before any change is applied.

Related Reading

• Elasticsearch nested field data type: when and why to use nested fields in the first place.
• Elasticsearch flattened field data type: the right alternative when you don't need correlated inner queries.
• Elasticsearch index.mapping.total_fields.limit: the separate field-count cap that often confuses with this one.
• Elasticsearch IllegalArgumentException: mapper conflicts: the typing error that often appears when reshaping nested mappings.
• Elasticsearch join two indexes: when splitting nested children into a separate index, you may need a join.
• Elasticsearch create index with mapping: set the nested_objects.limit at index creation time.