{"id":1855,"date":"2021-05-31T05:54:44","date_gmt":"2021-05-31T05:54:44","guid":{"rendered":"https:\/\/www.aeologic.com\/blog\/?p=1855"},"modified":"2026-04-30T13:43:06","modified_gmt":"2026-04-30T08:13:06","slug":"circuit-breakers-ultimate-solr-guide","status":"publish","type":"post","link":"https:\/\/www.aeologic.com\/blog\/circuit-breakers-ultimate-solr-guide\/","title":{"rendered":"Circuit Breakers \u2013 Ultimate Solr Guide"},"content":{"rendered":"
\n

As modern search applications scale, maintaining system stability under heavy query loads becomes a critical challenge. Solr Circuit Breaker Configuration<\/strong><\/a> plays a vital role in ensuring that Apache Solr nodes do not get overwhelmed by excessive traffic, memory pressure, or CPU spikes. By intelligently rejecting requests during high resource utilization, circuit breakers help preserve system performance, prevent node crashes, and maintain a consistent user experience. This approach allows organizations to prioritize reliability over raw throughput, making it an essential strategy for enterprise-grade Solr deployments.<\/p>\n<\/section>\n

\n

When To Use Circuit Breakers<\/h2>\n

Circuit breakers should be used when the user wishes to trade request throughput for a higher Solr stability. If circuit breakers are enabled, requests may be rejected under the condition of high node duress with an appropriate HTTP error code (typically 503).<\/p>\n

It is up to the client to handle this error and potentially build a retrial logic as this should ideally be a transient situation.<\/p>\n<\/section>\n

\n

What\u2019s New in Solr 9.x Circuit Breakers?<\/h2>\n

With the release of Apache Solr 9.x<\/strong>, circuit breaker capabilities have become more robust, configurable, and production-ready. While earlier versions provided basic protection mechanisms, Solr 9.x enhances stability by offering better integration with modern infrastructure environments and improved monitoring capabilities.<\/p>\n

One of the most significant improvements is the refinement of JVM heap and CPU-based circuit breakers<\/strong>, making them more responsive to real-time node stress. Solr 9.x ensures that nodes under pressure can gracefully reject requests rather than degrade performance or crash entirely.<\/p>\n

Additionally, Solr 9.x aligns better with cloud-native deployments<\/strong><\/a>, allowing circuit breakers to work efficiently in containerized environments like Docker and orchestration platforms such as Kubernetes.<\/p>\n

These enhancements make circuit breakers not just a safety feature, but a core reliability mechanism<\/strong> for enterprise-grade Solr deployments.<\/p>\n

Circuit Breaker Configurations<\/h2>\n

All circuit breaker configurations are listed in the circuitBreaker tags in solrconfig.xml as shown below:<\/p>\n

\n
<\/code><\/pre>\n
<circuitBreaker class=\"solr.CircuitBreakerManager\" enabled=\"true\">\r\n  <!-- All specific configs in this section -->\r\n<\/circuitBreaker><\/code><\/pre>\n
<\/code><\/pre>\n<\/div>\n
The “enabled” attribute controls the global activation\/deactivation of circuit breakers. If this flag is disabled, all circuit breakers will be disabled globally. Per circuit breaker configurations are specified in their respective sections later.<\/p>\n
This attribute acts as the highest authority and global controller of circuit breakers. For using specific circuit breakers, each one needs to be individually enabled in addition to this flag being enabled.<\/p>\n
CircuitBreakerManager is the default manager for all circuit breakers that should be defined in the tag unless the user wishes to use a custom implementation.<\/p>\n<\/section>\n
\n
\"IT<\/a>Detailed Circuit Breaker Configuration Examples<\/h2>\n
Configuring circuit breakers correctly is essential to achieving the right balance between performance and stability<\/strong>. Below is a more comprehensive configuration example:<\/p>\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
<circuitBreaker<\/span> class<\/span>=<\/span>“solr.CircuitBreakerManager”<\/span> enabled<\/span>=<\/span>“true”<\/span>><\/span>
\n<!– JVM Memory Circuit Breaker –><\/span>
\n<str<\/span> name<\/span>=<\/span>“memEnabled”<\/span>><\/span>true<\/str><\/span>
\n<str<\/span> name<\/span>=<\/span>“memThreshold”<\/span>><\/span>75<\/str><\/span><!– CPU Circuit Breaker –><\/span>
\n<str<\/span> name<\/span>=<\/span>“cpuEnabled”<\/span>><\/span>true<\/str><\/span>
\n<str<\/span> name<\/span>=<\/span>“cpuThreshold”<\/span>><\/span>80<\/str><\/span>
\n<\/circuitBreaker><\/span> <\/p>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n
Currently Supported Circuit Breakers<\/h2>\n
\n
JVM Heap Usage-Based Circuit Breaker<\/h3>\n
This circuit breaker tracks JVM heap memory usage and rejects incoming search requests with a 503 error code if the heap usage exceeds a configured percentage of maximum heap allocated to the JVM (-Xmx). The main configuration for this circuit breaker is controlling the threshold percentage at which the breaker will trip.<\/p>\n
Configuration for JVM heap usage-based circuit breaker:<\/p>\n
\n
<\/code><\/pre>\n
<str name=\"memEnabled\">true<\/str><\/code><\/pre>\n
<\/code><\/pre>\n<\/div>\n
Note that this configuration will be overridden by the global circuit breaker flag\u2009\u2014\u2009if circuit breakers are disabled, this flag will not help you.<\/p>\n
The triggering threshold is defined as a percentage of the max heap allocated to the JVM. It is controlled by the below configuration:<\/p>\n
\n
<\/code><\/pre>\n
<str name=\"memThreshold\">75<\/str><\/code><\/pre>\n
<\/code><\/pre>\n<\/div>\n
It does not logically make sense to have a threshold below 50% and above 95% of the max heap allocated to the JVM. Hence, the range of valid values for this parameter is [50, 95], both inclusive.<\/p>\n
Consider the following example:<\/p>\n
JVM has been allocated a maximum heap of 5GB (-Xmx) and memoryCircuitBreakerThresholdPct is set to 75. In this scenario, the heap usage at which the circuit breaker will trip is 3.75GB.<\/p>\n<\/section>\n
\n
CPU Utilization Based Circuit Breaker<\/h3>\n
This circuit breaker tracks CPU utilization and triggers if the average CPU utilization over the last one minute exceeds a configurable threshold. Note that the value used in the computation is over the last one minute\u2009\u2014\u2009so a sudden spike in traffic that goes down might still cause the circuit breaker to trigger for a short while before it resolves and updates the value.<\/p>\n
Configuration for CPU utilization based circuit breaker:<\/p>\n
\n
<\/code><\/pre>\n
<str name=\"cpuEnabled\">true<\/str><\/code><\/pre>\n
<\/code><\/pre>\n<\/div>\n
Note that this configuration will be overridden by the global circuit breaker flag\u2009\u2014\u2009if circuit breakers are disabled, this flag will not help you.<\/p>\n
The triggering threshold is defined in units of CPU utilization. The configuration to control this is as below:<\/p>\n
\n
<\/code><\/pre>\n
<str name=\"cpuThreshold\">75<\/str><\/code><\/pre>\n
<\/code><\/pre>\n<\/div>\n<\/section>\n<\/section>\n
\n
Circuit Breakers in Docker & Cloud Environments<\/h2>\n
Modern Solr deployments are increasingly containerized. Running Solr inside Docker introduces new challenges because resource limits are enforced at the container level<\/strong>, not the host.<\/p>\n
Key Challenge<\/h3>\n
If your container has:<\/p>\n