elasticsearch 'circuit_breaking_exception: Data too large' on aggregations: how to fix

TL;DR

Narrow the aggregation before reaching for bigger heap. Add filters to shrink the document set, lower the terms aggregation size, and aggregate on keyword fields instead of analyzed text. The circuit breaker tripped because the aggregation tried to load more field data into memory than the node allows.

{
  "type": "circuit_breaking_exception",
  "reason": "[parent] Data too large, data for [my-agg] would be [125829120/120mb], which is larger than the limit of [125829120/120mb]"
}

Steps

1. Read the error's reason field: it names which breaker tripped (parent, fielddata, or request) and which aggregation. Expected: you know the exact agg and the exact breaker.
2. Check whether the agg runs on a text field. Aggregations on analyzed text load fielddata, which is expensive; switch to the keyword sub-field (for example my_field.keyword). Expected: the mapping confirms the field has a keyword sub-field you can use.
3. Narrow the query with a filter (a time range, a term filter) so the agg runs over fewer documents. Expected: the same aggregation over a smaller set completes.
4. Cap the terms aggregation: set size to something small (10 to 100) and keep shard_size modest; avoid huge size values that force every shard to build giant bucket lists. Expected: memory per shard drops sharply.
5. Only if the aggregation is legitimately large, raise the heap or the breaker limit as a last resort, and plan to pre-aggregate with a rollup or transform instead. Expected: the query passes, and you have a plan to avoid needing the bigger limit.

Use this when

• Aggregations fail with circuitbreakingexception
• The error says "Data too large" and names an aggregation
• Dashboards with heavy terms aggs start failing as data grows
• The same aggregation worked last month on a smaller index

Not for this skill when

• The breaker trips on indexing (that is bulk-indexing pressure, a different fix)
• You get toomanybuckets_exception (that is the bucket-count guard; narrow the agg or raise the max)
• Plain search queries OOM a node with no aggregations involved

Variant phrasings

• elasticsearch data too large aggregation
• elasticsearch parent circuit breaker tripped
• elasticsearch fielddata circuit breaking exception
• how to fix circuitbreakingexception

Why it happens

Aggregations build in-memory data structures per shard (ordinals, buckets). The circuit breaker estimates the memory before allocating and refuses when the estimate exceeds the limit. That protects the node from a real OOM, at the cost of failing your query.

Edge cases

• Composite aggregations paginate through buckets without the giant in-memory build; use them for exhaustive bucket lists.
• A date_histogram with tiny intervals over a wide range explodes bucket counts; widen the interval.
• The estimate can overshoot on high-cardinality fields; run a cardinality agg first to see what you are dealing with.
• Raising the breaker limit without narrowing the agg just postpones the failure to the next data growth spurt.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_GnYoGhSCeyXzKm04K--TEw