How to fix UnavailableShardsException: [index][shard] primary shard is not active in Elasticsearch

ElasticsearchADVANCEDCRITICALUpdated Dec 29, 2025· 168 views

This Elasticsearch error occurs when one or more primary shards in an index are not allocated or active in the cluster, returning a 503 service unavailable response. The cluster is in a red health state, preventing reads and writes. Common causes include cluster recovery delays, insufficient disk space, or node failures.

Quick fix

Fixes UnavailableShardsException

GET _cluster/health
  1. Check cluster health status
  2. Check disk space on all nodes
  3. Wait for cluster recovery (if recently restarted)
  4. Manually retry shard allocation if stuck
elasticsearch — error
GET _cluster/health
UnavailableShardsException: [index][shard] primary shard is not active

What this error means

UnavailableShardsException with "primary shard is not active" indicates that a cluster cannot find or activate a required primary shard for an index. Elasticsearch returns HTTP 503 (Service Unavailable) and blocks all operations on that index. Unlike replica shards (which can be recreated from the primary), a missing primary shard means data is unavailable. This error typically occurs after cluster restarts, node failures, or when shards fail to reallocate due to resource constraints. The cluster health state becomes RED when primary shards are unassigned, meaning Elasticsearch cannot guarantee full index availability. This is a critical issue that requires immediate investigation.

Typical symptoms

  • HTTP 503 responses when querying or indexing: "primary shard is not active"
  • Cluster health shows RED status with unavailable shards
  • Kibana shows red index icons or reports missing primary shards
  • Indexing requests timeout with "UnavailableShardsException"
  • Search queries return "all shards failed" errors
  • Applications receive "Service Unavailable" responses

Common causes

  1. Cluster recovery in progress: After a restart or crash, Elasticsearch is still recovering and has not yet assigned primary shards
  2. Insufficient disk space: Nodes with over 85% disk usage (low watermark) cannot receive new shard allocations, blocking recovery
  3. Node failure or disconnect: A node containing the primary shard went down and the cluster has not yet elected a new primary
  4. Unmet version compatibility: Replica shards cannot be allocated to nodes with older Elasticsearch versions than the primary
  5. Corrupted or stale shard copies: All copies of a shard are marked as stale or corrupted, preventing allocation
  6. Network partitions: Nodes cannot communicate with the cluster master, preventing shard allocation decisions

How to fix "UnavailableShardsException: [index][shard] primary shard is not active"

1Check cluster health status

First, verify the cluster health and identify which indices have unassigned shards:

bash
GET _cluster/health

This returns the overall cluster state. If status is RED, you have unassigned primary shards. To see detailed shard allocation info:

bash
GET _cat/shards?v&h=index,shard,prirep,state,node,reason

Look for rows with state=UNASSIGNED and prirep=p (primary). The "reason" column explains why the shard is unassigned.

2Check disk space on all nodes

Verify that all nodes have adequate disk space available:

bash
GET _cat/nodes?v&h=name,diskAvail,diskUsed,diskPercent

If any node shows diskPercent >= 85%, Elasticsearch will not allocate shards to that node (low watermark threshold). Free up disk space by:
- Deleting old indices
- Increasing disk capacity
- Archiving data to external storage

Once disk usage drops below 85%, shards should begin reallocating automatically.

3Wait for cluster recovery (if recently restarted)

After a cluster restart or node failure, Elasticsearch delays shard reallocation by default (30 seconds) to avoid unnecessary rebalancing if the node recovers. Monitor progress:

bash
GET _cat/recovery?v&h=index,shard,stage,files_recovered,files_total

If shards are INITIALIZING or TRANSLOG, recovery is in progress—let it complete. This can take minutes to hours for large indices. Do not interrupt the process. Check recovery progress periodically until all shards reach DONE state.

4Manually retry shard allocation if stuck

If shards remain unassigned after 5-10 minutes despite adequate disk space, manually trigger reroute to retry allocation:

bash
POST _cluster/reroute?retry_failed=true

This retries shards that have exceeded max allocation failures. Check the response for deciders that blocked allocation—common ones include:
- DISK_THRESHOLD: Insufficient disk space
- AWARENESS: Shard replica distribution across nodes/racks
- SAME_SHARD_HOST: Replica shard assigned to same host as primary

After reroute, monitor cluster health again:

bash
GET _cluster/health
5Restore from snapshot if data is lost

If a primary shard is permanently lost and all replicas are unavailable, you must restore from a snapshot:

bash
GET _snapshot

To list available snapshots:

bash
GET _snapshot/my-repo/_all

To restore a specific index:

bash
POST _snapshot/my-repo/my-snapshot/_restore
{
  "indices": "my-index"
}

This creates a new index from the snapshot. If the original index is blocking recovery, delete it first:

bash
DELETE my-index
6Check node versions for version mismatch

Verify all nodes in the cluster are running the same Elasticsearch version:

bash
GET _cat/nodes?v&h=name,version

If versions differ, upgrade all nodes to the same version. Elasticsearch does not support mixed-version clusters. Replica shards cannot be allocated to nodes running older versions than the primary shard's version.

Perform a rolling upgrade:
1. Stop one node
2. Upgrade Elasticsearch and plugins
3. Restart the node
4. Wait for cluster to stabilize (shards rebalance)
5. Repeat for each remaining node

Advanced notes

Advanced Diagnostics:

Use the Cluster Allocation Explain API to get detailed reasons why a specific shard cannot be allocated:

bash
GET _cluster/allocation/explain
{
  "index": "my-index",
  "shard": 0,
  "primary": true
}

This shows all allocation deciders and which ones rejected the shard.

For persistent allocation issues, check the master node logs for allocation-related messages. Elasticsearch master logs contain detailed decider decisions.

If using managed Elasticsearch (AWS, Elastic Cloud), check service status pages and contact support if node health is affected.

For very large indices, recovery can take hours. Monitor using _recovery endpoint and do not trigger unnecessary reroutes during active recovery, as it can extend recovery time.

Consider setting index.number_of_replicas=0 as a temporary workaround for critical single-node clusters, but this disables fault tolerance and should only be used in testing or when the index can be deleted and recreated.

Frequently asked questions

What does "UnavailableShardsException" mean?
UnavailableShardsException with "primary shard is not active" indicates that a cluster cannot find or activate a required primary shard for an index. Elasticsearch returns HTTP 503 (Service Unavailable) and blocks all operations on that index. Unlike replica shards (which can be recreated from the primary), a missing primary shard means data is unavailable.
How do I fix "UnavailableShardsException"?
This Elasticsearch error occurs when one or more primary shards in an index are not allocated or active in the cluster, returning a 503 service unavailable response. The cluster is in a red health state, preventing reads and writes. Common causes include cluster recovery delays, insufficient disk space, or node failures.
What causes "UnavailableShardsException"?
Cluster recovery in progress: After a restart or crash, Elasticsearch is still recovering and has not yet assigned primary shards Insufficient disk space: Nodes with over 85% disk usage (low watermark) cannot receive new shard allocations, blocking recovery Node failure or disconnect: A node containing the primary shard went down and the cluster has not yet elected a new primary
Is the "UnavailableShardsException" error serious?
Yes. This is a critical-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading