GET _cluster/health
{
"status" : "yellow",
"unassigned_shards" : 12,
...
}
The cluster has been yellow for a week, or it just went red and searches are failing. Both colors mean the same thing: some shards are not assigned to any node. The difference is which shards, and Elasticsearch will tell you exactly why.
What the colors mean
- Green: every primary and replica shard is assigned.
- Yellow: every primary is assigned, so all data is searchable, but at least one replica isn't. You've lost redundancy, not data. Another node failure could turn it red.
- Red: at least one primary is unassigned. Searches on that index return partial results or fail, and writes to those shards fail.
Step 1: find the unassigned shards
GET _cat/shards?v&h=index,shard,prirep,state,unassigned.reason&s=state
prirep is p for primary and r for replica. unassigned.reason gives a first hint: NODE_LEFT, ALLOCATION_FAILED, INDEX_CREATED, CLUSTER_RECOVERED, and so on.
Step 2: ask the cluster why
GET _cluster/allocation/explain
{
"index": "logs-2026.09.26",
"shard": 0,
"primary": false
}
With no body, it explains the first unassigned shard it finds. The response lists every node and the decider that said no, for example:
"deciders": [{
"decider": "disk_threshold",
"decision": "NO",
"explanation": "the node is above the high watermark cluster setting [cluster.routing.allocation.disk.watermark.high=90%] ..."
}]
Always start here. It's much faster than guessing.
The common causes
1. A single-node cluster with replicas. Elasticsearch never puts a replica on the same node as its primary. With one node and number_of_replicas: 1 (the default for many indices), the cluster is yellow forever. Either add a node, or accept no replicas on a dev box:
