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

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

GET _cluster/health

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

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.

Verify that all nodes have adequate disk space available:

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.

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:

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.

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

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:

GET _cluster/health

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

GET _snapshot

To list available snapshots:

GET _snapshot/my-repo/_all

To restore a specific index:

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:

DELETE my-index

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

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