The cluster allocation API helps diagnose why Elasticsearch has not assigned a shard to a node. This is especially useful when cluster health is YELLOW or RED, or when an index cannot read or write because a shard is unassigned. section 14.1.2 section 15.3.2
Explain an unassigned replica
On a single-node cluster, the chats index can have an unassigned replica because Elasticsearch cannot place two copies of the same shard on one node: GET _cluster/allocation/explain { "index": "chats", "shard": 0, "primary": false } The response reports current_state as unassigned, describes why allocation is not permitted, and lists node-allocation deciders. A same_shard decision can explain that another copy already occupies the node. Adding another node allows the replica to be created and improves resilience. section 14.1.2
The API can select an unassigned shard when the request omits shard details. For focused troubleshooting, provide the index, shard number, primary status, and, when relevant, the current node. section 15.3.2
Read the explanation as a troubleshooting path:
- Check current_state to confirm that the shard is unassigned. section 15.3.2
- Read allocate_explanation for Elasticsearch’s overall reason. section 15.3.2
- Inspect node_allocation_decisions and their deciders for specific blockers such as same_shard or disk_threshold. section 15.3.2
- Use the findings to correct allocation conditions and return the cluster toward GREEN health. section 15.3.2
Listing 14.2 Asking the cluster for a shard failure explanation
GET _cluster/allocation/explain
{
"index": "chats",
"shard": 0,
"primary": false
}
Open the request listing for a concrete shard-allocation explanation, then compare it with the condensed response showing the current state and decider reasoning. section 14.1.2
