On this page
Short answer
Most Elasticsearch incidents trace to three numbers: how much heap a node has, how many shards it carries, and how full its disks are. Keep heap at or below half of memory and under the compressed-pointer limit, keep shards between 10GB and 50GB and under 1,000 per node, and keep disks below the 85% watermark. This guide gives the checks and API calls behind each. It is for teams who run their own clusters and want to know when to call for Elasticsearch support.
Most Elasticsearch incidents trace to three numbers: how much heap a node has, how many shards it carries, and how full its disks are. Keep heap at or below half of memory and under the compressed-pointer limit, keep shards between 10GB and 50GB and under 1,000 per node, and keep disks below the 85% watermark. This guide gives the checks and API calls behind each. It is for teams who run their own clusters and want to know when to call for Elasticsearch support.
How much heap should an Elasticsearch node have?
Set the minimum and maximum heap (Xms and Xmx) to the same value, keep it at or below 50% of the memory available to the node, and keep it under the compressed ordinary object pointers threshold. Elastic's JVM settings page says 26GB is safe on most systems and up to 30GB on some. Elastic also notes that Elasticsearch sets heap automatically from each node's roles and memory and recommends the default sizing for most production environments, so override it only with a reason.
Verify, do not assume:
- The startup log line reads like
heap size [1.9gb], compressed ordinary object pointers [true]. GET _nodes?filter_path=**.jvm.using_compressed_ordinary_object_pointersshows the same.GET _cat/nodes?v&h=name,heap.percent,heap.max,ram.percentshows pressure per node.
Heap that stays high after garbage collection is the warning sign, not a spike during a query.
What do the circuit breakers tell you?
They tell you which request type is eating heap. Defaults from the circuit breaker settings page:
| Breaker | Setting | Default |
|---|---|---|
| Parent | indices.breaker.total.limit | 95% of heap with real-memory accounting (70% without) |
| Fielddata | indices.breaker.fielddata.limit | 40% of heap |
| Request | indices.breaker.request.limit | 60% of heap |
| In-flight requests | network.breaker.inflight_requests.limit | 100% of heap, bounded by the parent |
GET _nodes/stats/breaker shows trip counts per node. Fielddata trips point at sorting or aggregating on a text field; request trips point at a large aggregation. Raising a limit moves the failure, so fix the query or mapping first.
How many shards is too many?
Elastic's sizing guidance is to target shards of 10GB to 50GB, keep each shard below 200 million documents, and keep non-frozen shards to no more than 1,000 per node by default. For dedicated master nodes, keep fewer than 3,000 indices per GB of master heap: four-gigabyte heaps support fewer than 12,000 indices.
| Symptom | Likely cause | Check |
|---|---|---|
| Master CPU high, cluster state updates slow | Thousands of tiny shards | GET _cluster/stats (total shards, mapping size) |
| Search slow with flat data volume | Many small shards searched per query | GET _cat/shards?v&s=store |
| Heap high on data nodes | Mapping overhead per shard | total_estimated_overhead in _nodes/stats |
| Empty indices piling up | Rollover on max_age with no data | GET _cat/count/<pattern> |
Fix with index lifecycle management: set max_primary_shard_size to 50gb and min_primary_shard_size to 10gb on rollover, and use _shrink, _split or _reindex for indices already sized wrong. cluster.max_shards_per_node can be raised temporarily, and Elastic's page says to reset it to null once the long-term fix is in. To avoid hotspots, index.routing.allocation.total_shards_per_node caps shards per node per index.
Why is the cluster yellow or red?
Yellow means replicas are unassigned; red means at least one primary is. Ask the cluster, one shard at a time:
`` GET _cluster/health?level=indices GET _cat/shards?v&h=index,shard,prirep,state,unassigned.reason POST _cluster/allocation/explain ``
The allocation explain API reports why a shard is unassigned, or why it stays where it is, with the decision of each allocation decider. The most common answer is disk. Elastic's allocation settings page gives these defaults:
| Watermark | Default (disk used) | Effect |
|---|---|---|
| Low | 85% | No new shards allocated to the node |
| High | 90% | Elasticsearch tries to move shards off the node |
| Flood stage | 95% | index.blocks.read_only_allow_delete applied to indices on the node |
The flood-stage block is removed automatically once usage falls below the high watermark. Free space first; raising watermarks is a stopgap.
What should you check every week?
| Check | Call | Healthy sign |
|---|---|---|
| Heap after GC | _cat/nodes?h=name,heap.percent | Not trending up |
| Breaker trips | _nodes/stats/breaker | Zero or flat |
| Shard size | _cat/shards?s=store:desc | Largest under 50GB, most over 10GB |
| Shards per node | _cat/allocation?v | Under 1,000 |
| Disk | _cat/allocation?v | Below 85% |
| Empty indices | _cat/count | None |
| ILM | GET <index>/_ilm/explain | No index stuck on a step |
| Snapshots | GET _snapshot/_all/_all | A recent success you have restored from |
Test the restore. A snapshot that reports success has not proved you can recover.
When to call for help
Call when the cluster is red and allocation/explain points at something you cannot change, when heap stays above the compressed-pointer limit or breakers keep tripping after a query fix, or when shard counts have outgrown the cluster state. AceMQ provides 24/7 Elasticsearch and OpenSearch support across the Americas, EMEA and APAC, with response targets from 15 minutes, by plan, and quote replies within 1 hour. Support typically runs $24,000-72,000 a year (USD), by SLA, scope and deployment. See also who offers Elasticsearch support and Elasticsearch pricing. Many of these API names also exist in OpenSearch; check that project's documentation for defaults.
Sources
- Elastic docs, size your shards: elastic.co/docs/deploy-manage/production-guidance/optimize-performance/size-shards
- Elastic docs, JVM settings: elastic.co/docs/reference/elasticsearch/jvm-settings
- Elastic docs, circuit breaker settings: elastic.co/docs/reference/elasticsearch/configuration-reference/circuit-breaker-settings
- Elastic docs, cluster-level shard allocation and routing settings: elastic.co/docs/reference/elasticsearch/configuration-reference/cluster-level-shard-allocation-routing-settings
- Elastic API docs, cluster allocation explain: elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-allocation-explain
Frequently Asked Questions
What is the right Elasticsearch heap size?
Equal `Xms` and `Xmx`, at most 50% of node memory and under about 26GB (up to 30GB on some systems), per Elastic's JVM settings page. The default automatic sizing is recommended for most production use.
How many shards per node is safe?
Elastic's default limit is 1,000 non-frozen shards per node. Target 10GB to 50GB per shard.
Why did my indices turn read-only?
A node passed the 95% flood-stage disk watermark, so `index.blocks.read_only_allow_delete` was applied. It lifts when usage drops below 90%.
What does the cluster allocation explain API do?
It explains why a shard is unassigned or has not moved, including each allocation decider's decision.
What causes circuit breaker exceptions?
Requests that would push heap past a breaker limit: parent 95%, fielddata 40%, request 60% by default. Fix the query or mapping before changing limits.
Guides, comparisons and research
Go deeper on support and version lifecycles
Comparisons
9- PostgreSQL vs MySQL: Where They Differ and How to Choose
- OpenSearch vs Elasticsearch: How the Fork Has Diverged
- Enterprise Support Compared 2026: Databricks, Snowflake, MuleSoft, Boomi, Datadog and Splunk
- Kong Alternatives and Competitors Compared
- Splunk Alternatives and Replacements Compared
- MuleSoft Alternatives and Competitors Compared
