Document synonyms filter circuit breaker behavior (ES 9.4 / serverless)

[Copilot]

ES 9.4 and serverless added a real memory circuit breaker check during synonyms map construction to prevent OOMs with large synonym rule sets. This behavior was undocumented.

Changes

• solutions/search/full-text/search-with-synonyms.md: Added warning block in the token filter configuration section covering:
  • Circuit breaker trips at >95% JVM heap usage
  • lenient: true → empty synonyms map used, event logged; lenient: false (default) → index goes red
  • indices.breaker.total.limit is configurable in ECH/self-managed; not configurable in serverless
  • Scoped with {applies_to} tags: stack: ga 9.4 and serverless: ga

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Internal]: Document synonyms filter circuit breaker behavior</issue_title>
<issue_description>### Description

In ES 9.4 and serverless, we added a real memory circuit breaker check while building the synonyms map to prevent synonym and synonym_graph token filters from causing OOMs when processing large numbers of synonym rules. By default, the circuit breaker will trip when more than 95% of heap memory is in use.

Behavior on circuit breaker trip is determined by the filter's lenient param value:

• If true, an empty synonyms map is used and the event is logged in the ES logs
• If false, the affected index goes into red state

We need to update the documentation for the synonym and [synonym_graph](https://github.com/elastic/elasticsearch/edit/main/docs/reference/text-analysis/analysis-synonym-graph-tokenfilter.md) token filters to call out this circuit breaker behavior.

Resources

This feature was implemented in elastic/elasticsearch#141669

This feature is tracked by the GH issue elastic/elasticsearch#140564

Which documentation set does this change impact?

Elastic On-Prem and Cloud (all)

Feature differences

The only difference between environments is that circuit breaker limits are not configurable in serverless. In ECH and on-prem, the real memory circuit breaker limit is configurable via the indices.breaker.total.limit cluster setting.

What release is this request related to?

9.4

Serverless release

The week of February 16, 2026

Collaboration model

The documentation team

Point of contact.

Main contact: @Mikep86

Stakeholders: @Mikep86 @jimczi @liranabn @dustincoates
</issue_description>

<agent_instructions>use https://github.com/elastic/elastic-docs-skills to help you</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes [Internal]: Document synonyms filter circuit breaker behavior #5522

---

⌨️ Start Copilot coding agent tasks without leaving your editor — available in VS Code, Visual Studio, JetBrains IDEs and Eclipse.