Elasticsearch Elasticsearch Shard Allocation Status

By Opster Team

Updated: Nov 7, 2023

| 2 min read

Quick links


Elasticsearch utilizes a concept known as sharding to distribute data across multiple nodes. This article delves into the intricacies of Elasticsearch shard allocation status, providing a comprehensive understanding of its functionality, importance, and troubleshooting methods.

Shard allocation is a crucial aspect of Elasticsearch’s architecture. It is the process by which Elasticsearch distributes data shards across the nodes in a cluster. The allocation status of a shard provides insights into its current state and location within the cluster. 

Shard allocation statuses

There are several shard allocation statuses that you may encounter while working with Elasticsearch:

  1. Unassigned: This status indicates that the shard has not yet been allocated to any node. This could be due to a new index creation, a node failure, or a shard relocation. This can also be due to the fact that your cluster has less nodes than the number of replica shards plus the primary, since primary and replica shards cannot be allocated to the same node. Usually, if you have a one node cluster and an index with one primary and one replica shards, the replica shard will always be unassigned, because there is no node to host it.
  2. Initializing: The shard is in the process of being allocated to a node and is not yet ready to serve requests.
  3. Started: The shard has been successfully allocated to a node and is ready to serve requests.
  4. Relocating: The shard is in the process of being moved from one node to another.

Understanding these statuses is essential for managing and troubleshooting your Elasticsearch cluster effectively.

For instance, if a large number of shards remain in the ‘Unassigned’ state for an extended period, it could indicate a problem with the cluster’s health. This could be due to insufficient disk space, network issues, or configuration errors, such as having too few data nodes provisioned compared to the number of configured primary and replica shards.

To check the allocation status of shards, you can use the `_cat/shards` API. Here’s an example:

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

This command will return a list of all shards, their primary or replica status (prirep), their current state, and the reason if they are unassigned. Another useful command to investigate why shards stay in the unassigned state is the `_cluster/allocation/explain` command:

GET _cluster/allocation/explain

This command provides a list of all unassigned shards as well as the reason why the shards cannot be allocated.


If you encounter issues with shard allocation, there are several steps you can take to troubleshoot:

  1. Check Cluster Health: Use the `_cluster/health` API to get an overview of your cluster’s health. If the status is yellow or red, it indicates issues that need to be addressed.
  2. Review Shard Allocation Settings: Ensure that your shard allocation settings are correctly configured. For instance, the `cluster.routing.allocation.enable` setting should not be set to ‘none’ unless necessary, for instance like when performing a rolling upgrade
  3. Inspect Node Health: Use the `_cat/nodes` API to check the health and status of individual nodes. Look for any nodes that are disconnected or in a bad state.
  4. Examine Disk Usage: Use the `_cat/allocation` API to check disk usage. If a node is nearing its disk watermark, it may not be able to allocate new shards.
  5. Check for Network Issues: Network problems between nodes can prevent shard allocation. Use tools like `ping` or `telnet` to test network connectivity.
  6. Review Elasticsearch Logs: The logs can provide valuable insights into what’s causing the shard allocation issues.


By understanding the Elasticsearch shard allocation status and knowing how to troubleshoot potential issues, you can ensure the smooth operation of your Elasticsearch cluster. Remember, regular monitoring and proactive management are key to maintaining a healthy and efficient Elasticsearch environment.