OpenSearch Cluster Status Showing Yellow Due to Unassigned Replica Shards

Hello @Leo Walker

Yes, a yellow OpenSearch cluster means the primary shards are allocated, but one or more replicas are unassigned. The cluster remains operational, but you don't currently have the intended replica redundancy.

Don't force the replica allocation as the first step. Start by identifying the unassigned shards:

GET /_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason

Then ask OpenSearch why one of them cannot be allocated:

POST /_cluster/allocation/explain?include_disk_info=true
{
  "index": "<index-name>",
  "shard": 0,
  "primary": false
}

The Cluster Allocation Explain API will tell you which allocation decider is blocking that replica and why. Common causes include insufficient eligible data nodes, disk watermarks, allocation filters, shard limits, allocation awareness/forced awareness, or a disabled allocation.

A very common case is a single-data-node cluster with number_of_replicas: 1. OpenSearch won't place a primary and its replica on the same node, so that replica will intentionally remain unassigned. You cannot safely force it onto that same node.

In that situation, you either add another eligible data node or, if this is intentionally a single-node/non-HA environment, change the index replica count:

PUT /<index-name>/_settings
{
  "index": {
    "number_of_replicas": 0
  }
}

If the allocation explanation instead shows something such as disk_threshold, filter, awareness, or shards_limit, fix that underlying condition rather than overriding it.

There is a manual /_cluster/reroute API, but OpenSearch describes it as an advanced mechanism. If you eventually need it, first test with:

POST /_cluster/reroute?dry_run=true&explain=true

If the shard previously failed allocation and you've corrected the underlying problem, you can also ask OpenSearch to retry failed allocations:

POST /_cluster/reroute?retry_failed=true

OpenSearch specifically recommends using dry_run=true before applying manual reroute commands in production.

If you can share the output of /_cluster/allocation/explain with host/index-sensitive information removed, we should be able to identify exactly why those replicas remain unassigned.

References:

OpenSearch - Cluster Allocation Explain API

OpenSearch - Cluster Reroute API

OpenSearch - Cluster Health API

Help make this community better for everyone: If this answer helped or resolved your issue, please accept it or upvote it. If not, share more details in a comment so we can continue the discussion and find the right solution. Thank you.

Hello, When your OpenSearch cluster shows a yellow status, it means all primary shards are allocated but one or more replicas are not. This typically happens when the cluster does not have enough nodes to host the replicas, or when allocation rules prevent them from being assigned. The first thing to check is whether you have sufficient data nodes available. If you only have one node, replicas cannot be assigned, and the cluster will remain yellow by design. If you have multiple nodes, verify that they are healthy and part of the cluster by running GET _cat/nodes?v and GET _cluster/health.

To force allocation of unassigned shards, you can use the reroute API. For example, run POST _cluster/reroute with a command block specifying the shard, index, and target node. A typical request looks like:

POST _cluster/reroute
{
  "commands": [
    {
      "allocate_replica": {
        "index": "your_index",
        "shard": 0,
        "node": "node-name"
      }
    }
  ]
}

This forces OpenSearch to assign the replica shard to the specified node. Before doing this, confirm that the node has enough disk space and that allocation filtering is not blocking it. You can check allocation explanations with GET _cluster/allocation/explain which will tell you why a shard is unassigned. If the issue is related to disk watermark thresholds, adjust the settings with PUT _cluster/settings and modify cluster.routing.allocation.disk.watermark.low or high accordingly. If it is related to node filters, review cluster.routing.allocation.exclude or include settings.

In short, the safe path is to first run GET _cluster/allocation/explain to understand why replicas are not being placed, then either add more nodes, adjust allocation rules, or use the reroute API to force placement. Forcing allocation without resolving the underlying constraint may lead to instability, so always validate the health of the nodes and the capacity before applying the reroute.

I hope you've found something useful here. If it helps you get more insight into the issue, it's appreciated to accept the answer. Should you have more questions, feel free to leave a message. Have a nice day!

DV.