Introduction

Elasticsearch circuit breaker triggered when query or aggregation memory exceeds limit. This guide provides step-by-step diagnosis and resolution.

Symptoms

Typical error output:

bash
ERROR: Circuit breaker triggered
parent circuit breaker triggered: real_memory_usage [12GB] > limit [10GB]
Rejecting request due to memory pressure

Common Causes

  1. 1.Query or aggregation uses too much memory
  2. 2.Field data cache consuming excessive heap
  3. 3.Request cache or query cache not sized properly
  4. 4.Circuit breaker limit too low for workload

Step-by-Step Fix

Step 1: Check Current State

bash
curl -XGET 'localhost:9200/_nodes/stats/breaker?pretty'
curl -XGET 'localhost:9200/_cluster/health?pretty'
curl -XGET 'localhost:9200/_nodes/stats/jvm?pretty'

Step 2: Identify Root Cause

bash
curl -XGET 'localhost:9200/_cluster/health?pretty'
curl -XGET 'localhost:9200/_nodes/stats?pretty'

Step 3: Apply Primary Fix

```bash # Increase circuit breaker limit PUT _cluster/settings { "persistent": { "indices.breaker.total.limit": "60%", "indices.breaker.fielddata.limit": "40%" } }

# Clear fielddata cache POST /_cache/clear?fielddata=true ```

Step 4: Apply Alternative Fix

```bash # Alternative fix: Check node stats GET _nodes/stats?pretty

# Update specific index settings PUT my-index/_settings { "index": { "refresh_interval": "30s" } }

# Verify the fix GET _cat/indices?v&index=my-index ```

Step 5: Verify the Fix

bash
curl -XGET 'localhost:9200/_nodes/stats/breaker?pretty'
curl -XGET 'localhost:9200/_nodes/stats/jvm?pretty'
# Circuit breaker tripped_count should not increase

Common Pitfalls

  • Not waiting for cluster state propagation after settings change
  • Using text field for aggregations instead of keyword
  • Setting circuit breaker limits too low for production workload
  • Ignoring disk watermark warnings until cluster blocks

Best Practices

  • Monitor cluster health regularly with _cluster/health API
  • Use keyword fields for aggregations to avoid fielddata
  • Set circuit breaker limits based on heap size
  • Configure ILM policies for automated index management
  • Elasticsearch Cluster Red Status
  • Elasticsearch Index Not Found
  • Elasticsearch Query Timeout
  • Elasticsearch Node High CPU