Error log: This error appears as the root_cause when you try to query an index that is in a red state.
JSON
None
{
"error": {
"root_cause": [
{
"type": "index_primary_shard_not_allocated_exception",
"reason": "primary shard is not allocated",
"index_uuid": "...",
"shard": "0",
"index": "my-red-index"
}
],
"type": "unavailable_shards_exception",
// ...
},
"status": 503
}Why… is this happening? This is the specific error that defines a red cluster status for a particular index. It means the primary shard (the main copy of your data) for that index is not assigned to any node.
Because the primary shard is offline, that piece of your data is completely unavailable. You cannot write to it, and you cannot read from it.
Common causes:
- Node failure (No Replica): The only node holding your primary shard failed, and there was no replica shard on another node to be promoted.
- Failed allocation: The cluster just restarted (or the index was just created) and OpenSearch is trying to assign the primary shard, but it’s failing (e.g., due to low disk space, allocation rules, or a corrupted shard).
- Cluster is still initializing: The cluster is starting up, and the cluster manager node simply hasn’t finished the allocation process yet.
Best Practice:
1. Check _cat/health: Confirm your cluster status is red.
2. Find the Unassigned Shard: Run GET /_cat/shards?v&h=index,shard,prirep,state,unassigned.reason and look for p (primary) shards in the UNASSIGNED state.
3. Use the Allocation Explain API (Most Important): This is your best tool. It will tell you exactly why the primary shard can’t be assigned.
Bash
None
GET /_cluster/allocation/explain
{
"index": "my-red-index",
"shard": 0,
"primary": true
}4. Fix the Underlying Issue: The explain API will give you the reason. “Disk threshold exceeded” means you need to free up disk. “No node matches allocation rules” means you need to check your settings.
5. Always Use Replicas: To prevent this from ever happening, always set number_of_replicas: 1 or more for your production indices.
What else can I do? Stuck with a red cluster? The output of the _cluster/allocation/explain API is the key. Post that output on the OpenSearch community forums, or contact us in The OpenSearch Slack Channel in #General.
