Error log: “ShardNotAvailableException” / “no such shard”

Error log: This error can appear in your OpenSearch logs or as a root_cause in a query failure when a specific shard cannot be found.

JSON

None
{

  "error": {

    "root_cause": [

      {

        "type": "shard_not_available_exception",

        "reason": "no such shard",

        "index_uuid": "...",

        "shard": "0",

        "index": "my-index"

      }

    ],

    "type": "search_phase_execution_exception",

    // ...

  },

  "status": 503

}

Why… is this happening? This is a low-level routing error. It means the cluster manager node thinks a shard (e.g., primary shard 0 of my-index) lives on a specific data node, so it sends the search request there. But when the request arrives, that data node reports, “I don’t have that shard.”

This indicates a mismatch between the cluster state (what the cluster manager thinks is true) and the node’s local state (what the data node knows is true).

Common causes:

1. Stale cluster state: The node receiving the request has a stale view of the cluster and hasn’t yet learned that the shard moved elsewhere. This can happen during heavy cluster churn (e.g., nodes joining/leaving).
2. Shard relocation/recovery: A shard was in the middle of being moved (relocated) to that node, or being recovered on that node, but the process failed or was cancelled. The cluster state updated, but the local data node is in a “half-built” state.
3. Data path corruption: In rare cases, the shard’s files on disk could be deleted or corrupted, but the node hasn’t realized it yet. When it tries to open the shard for the query, it fails.

Best Practice:

1. Check cluster health: Run GET /_cluster/health. Is it green? If it’s yellow or red, you have unassigned shards, which is the likely root cause.

2. Check _cat/shards: Run GET /_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason. Look for the specific index and shard from the error.

• • What state is it in? (e.G., INITIALIZING, RELOCATING, UNASSIGNED).
  • What is the unassigned.reason?

3. Force a reroute (with caution): If a shard is stuck UNASSIGNED and you’ve fixed the underlying problem (like disk space), you can try to manually force OpenSearch to re-evaluate:
JSON

None
POST /_cluster/reroute?retry_failed=true

4. Restart the node: If a single node is consistently reporting ShardNotAvailableException for shards it should have, it may have a stale cluster state. A restart of just that node will force it to rejoin the cluster and get the correct state.

What else can I do? If your shards are stuck UNASSIGNED and the _cluster/allocation/explain API (Blog #1) isn’t helping, this can be a complex recovery scenario. Reach out to the OpenSearch community or contact us in The OpenSearch Slack Channel in #General.