How to Fix Unassigned Shards in Elasticsearch Quickly

Unassigned shards in Elasticsearch happen when the cluster cannot allocate shards due to issues like node failures or configuration errors. To fix this, use the _cluster/allocation/explain API to find the cause, then resolve it by restarting nodes, increasing disk space, or adjusting shard allocation settings with _cluster/reroute.

Why This Happens

Unassigned shards occur when Elasticsearch cannot place a shard on any node. This can happen if a node crashed, disk space is low, or shard allocation rules prevent placement. For example, if a node is down, its shards become unassigned until the cluster recovers or reallocates them.

bash

GET /_cat/shards?v

# Shows shards with state UNASSIGNED

GET /_cluster/allocation/explain

# Explains why a shard is unassigned

Output

shard: 0
index: my_index
node: null
unassigned_info: {
  reason: 'NODE_LEFT',
  at: '2024-06-01T12:00:00Z'
}
can_allocate: false
allocate_explanation: 'cannot allocate because node left the cluster'

The Fix

First, check the reason for unassigned shards using _cluster/allocation/explain. Then fix the root cause: restart failed nodes, free disk space, or update shard allocation settings. Finally, use POST /_cluster/reroute to manually allocate shards if needed.

json

POST /_cluster/reroute
{
  "commands": [
    {
      "allocate_empty_primary": {
        "index": "my_index",
        "shard": 0,
        "node": "node-1",
        "accept_data_loss": true
      }
    }
  ]
}

Output

{
  "acknowledged": true
}

# After reroute, shards should be assigned and cluster green

Prevention

To avoid unassigned shards, monitor cluster health regularly and ensure nodes have enough disk space and memory. Use shard allocation awareness settings to distribute shards evenly. Also, configure cluster.routing.allocation settings to control shard placement and avoid single points of failure.

Related Errors

Similar issues include yellow cluster status caused by missing replicas and cluster red status when primary shards are unassigned. Fixes often involve adding nodes, increasing resources, or adjusting shard allocation settings.

Key Takeaways

Use _cluster/allocation/explain to find why shards are unassigned.

Fix node failures, disk space, or allocation rules to allow shard assignment.

Use _cluster/reroute API to manually assign shards if automatic allocation fails.

Monitor cluster health and configure shard allocation awareness to prevent issues.

Unassigned shards often indicate cluster resource or configuration problems.