Skip to main content
search
Error Logs

Unassigned Shards – Why Your Cluster is Showing Yellow or Red

By November 3, 2025No Comments

Error Log: You won’t typically see “unassigned_shards” directly in your log files as an error message. Instead, this is a status indicator you’d find when checking your cluster health:

JSON

 

GET _cat/shards?v

 

# Or from GET _cluster/health

{

  “cluster_name” : “your-opensearch-cluster”,

  “status” : “yellow”,  <– Or “red”

  “timed_out” : false,

  “number_of_nodes” : 3,

  “number_of_data_nodes” : 3,

  “active_primary_shards” : 100,

  “active_shards” : 150,

  “relocating_shards” : 0,

  “initializing_shards” : 0,

  “unassigned_shards” : 50,  <– Here’s the culprit!

  // …

}

 

Why… is this happening? unassigned_shards means that OpenSearch has not been able to allocate one or more shards (either primary or replica) to a node in your cluster.

  • Yellow Status: Indicates that all primary shards are active, but one or more replica shards are unassigned. Your data is safe and searchable, but you’ve lost the redundancy that replicas provide. If a node holding a primary shard fails, you could lose access to that data until a replica can be promoted (if one exists and can be assigned).
  • Red Status: This is critical! It means one or more primary shards are unassigned. This specific data is completely unavailable, and you cannot search or write to the indices that contain these primary shards.

Common reasons include:

  1. Node Down/Left: A node that held the primary or replica shard is no longer part of the cluster.
  2. Insufficient Disk Space: The nodes that could host the shard have passed a disk watermark (e.g., 85% full by default), preventing new shard allocation.
  3. Allocation Rules: You might have specific index.routing.allocation.require or exclude settings that prevent shards from being assigned.
  4. Shard Corruption: In rare cases, a shard might become corrupted and cannot be initialized.
  5. Cluster Restart: During a rolling restart, shards will temporarily become unassigned as nodes come back online. This is usually transient.

Best Practice:

  1. Monitor Disk Space: Proactively monitor disk usage on all your nodes. OpenSearch will start refusing to allocate shards (and eventually block writes) if disk space gets too low.
  2. Ensure Node Stability: Investigate why nodes are leaving the cluster (network issues, out-of-memory, crashes).
  3. Check Allocation Explain API: Use GET _cluster/allocation/explain with ?pretty&index=<index_name>&shard=<shard_id>&primary=<true/false> to get a detailed reason why a specific shard isn’t being assigned. This is your go-to tool for diagnosis.
  4. Allow Time for Recovery: After a node restart or failure, give the cluster time to automatically reallocate shards.

What else can I do? Are you battling persistent unassigned_shards or confused by allocation explanations? Don’t struggle alone! Reach out to the vibrant OpenSearch community for help and support.

You can also contact us directly for assistance on the OpenSearch Slack Channel 

 

Author