--- type: api title: Explain the shard allocations description: **All methods and paths for this operation:** url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/operation/operation-cluster-allocation-explain resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/operation/operation-cluster-allocation-explain products: - Elasticsearch --- # Explain the shard allocations Availability: 5.0+ ## Paths - `POST` (also `GET`) `/_cluster/allocation/explain` - [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/authentication#apikeyauth) - [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/authentication#basicauth) - [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/authentication#bearerauth) ## Description Get explanations for shard allocations in the cluster. This API accepts the current_node, index, primary and shard parameters in the request body or in query parameters, but not in both at the same time. For unassigned shards, it provides an explanation for why the shard is unassigned. For assigned shards, it provides an explanation for why the shard is remaining on its current node and has not moved or rebalanced to another node. This API can be very useful when attempting to diagnose why a shard is unassigned or why a shard continues to remain on its current node when you might expect otherwise. Refer to the linked documentation for examples of how to troubleshoot allocation issues using this API. [Cluster allocation API examples](https://www.elastic.co/docs/troubleshoot/elasticsearch/cluster-allocation-api-examples) ## Query String Parameters - `index` (string IndexName) The name of the index that you would like an explanation for. - `shard` (number) An identifier for the shard that you would like an explanation for. - `primary` (boolean) If true, returns an explanation for the primary shard for the specified shard ID. - `current_node` (string) Explain a shard only if it is currently located on the specified node name or node ID. - `include_disk_info` (boolean · default: false) If true, returns information about disk usage and shard sizes. - `include_yes_decisions` (boolean · default: false) If true, returns YES decisions in explanation. - `master_timeout` (string Duration · default: 30s) Period to wait for a connection to the master node. ## Request Body `application/json` - `index` (string IndexName) — optional The name of the index that you would like an explanation for. - `shard` (number) — optional An identifier for the shard that you would like an explanation for. - `primary` (boolean) — optional If true, returns an explanation for the primary shard for the specified shard ID. - `current_node` (string) — optional Explain a shard only if it is currently located on the specified node name or node ID. ## Response `application/json` - `allocate_explanation` (string) - `allocation_delay` (string Duration) - `allocation_delay_in_millis` (DurationValueUnitMillis) - `can_allocate` (enum Decision) Values: `yes`, `no`, `worse_balance`, `throttled`, `awaiting_info`, `allocation_delayed`, `no_valid_shard_copy`, `no_attempt` - `can_move_to_other_node` (enum Decision) Values: `yes`, `no`, `worse_balance`, `throttled`, `awaiting_info`, `allocation_delayed`, `no_valid_shard_copy`, `no_attempt` - `can_rebalance_cluster` (enum Decision) Values: `yes`, `no`, `worse_balance`, `throttled`, `awaiting_info`, `allocation_delayed`, `no_valid_shard_copy`, `no_attempt` - `can_rebalance_cluster_decisions` ([] AllocationDecision) - `decider` (string) - `decision` (enum AllocationExplainDecision) Values: `NO`, `YES`, `THROTTLE`, `ALWAYS` - `explanation` (string) - `can_rebalance_to_other_node` (enum Decision) Values: `yes`, `no`, `worse_balance`, `throttled`, `awaiting_info`, `allocation_delayed`, `no_valid_shard_copy`, `no_attempt` - `can_remain_decisions` ([] AllocationDecision) - `decider` (string) - `decision` (enum AllocationExplainDecision) Values: `NO`, `YES`, `THROTTLE`, `ALWAYS` - `explanation` (string) - `can_remain_on_current_node` (enum Decision) Values: `yes`, `no`, `worse_balance`, `throttled`, `awaiting_info`, `allocation_delayed`, `no_valid_shard_copy`, `no_attempt` - `cluster_info` ({} ClusterInfo) - `nodes` (map string to NodeDiskUsage) Map values ({} NodeDiskUsage) - `node_name` (string Name) - `least_available` ({} DiskUsage) - `path` (string) - `total_bytes` (number) - `used_bytes` (number) - `free_bytes` (number) - `free_disk_percent` (number) - `used_disk_percent` (number) - `most_available` ({} DiskUsage) - `path` (string) - `total_bytes` (number) - `used_bytes` (number) - `free_bytes` (number) - `free_disk_percent` (number) - `used_disk_percent` (number) - `shard_sizes` (map string to number) - `shard_data_set_sizes` (map string to string) - `shard_paths` (map string to string) - `reserved_sizes` ([] ReservedSize) - `node_id` (string Id) - `path` (string) - `total` (number) - `shards` ([] string) - `configured_delay` (string Duration) - `configured_delay_in_millis` (DurationValueUnitMillis) - `current_node` ({} CurrentNode) - `id` (string Id) - `name` (string Name) - `roles` (NodeRoles) Values: `master`, `data`, `data_cold`, `data_content`, `data_frozen`, `data_hot`, `data_warm`, `client`, `ingest`, `ml`, `voting_only`, `transform`, `remote_cluster_client`, `coordinating_only` - `attributes` (map string to string) - `transport_address` (string) - `weight_ranking` (number) - `current_state` (string) - `index` (string IndexName) - `move_explanation` (string) - `node_allocation_decisions` ([] NodeAllocationExplanation) - `deciders` ([] AllocationDecision) - `decider` (string) - `decision` (enum AllocationExplainDecision) Values: `NO`, `YES`, `THROTTLE`, `ALWAYS` - `explanation` (string) - `node_attributes` (map string to string) - `node_decision` (enum Decision) Values: `yes`, `no`, `worse_balance`, `throttled`, `awaiting_info`, `allocation_delayed`, `no_valid_shard_copy`, `no_attempt` - `node_id` (string Id) - `node_name` (string Name) - `roles` (NodeRoles) Values: `master`, `data`, `data_cold`, `data_content`, `data_frozen`, `data_hot`, `data_warm`, `client`, `ingest`, `ml`, `voting_only`, `transform`, `remote_cluster_client`, `coordinating_only` - `store` ({} AllocationStore) - `allocation_id` (string) - `found` (boolean) - `in_sync` (boolean) - `matching_size_in_bytes` (number) - `matching_sync_id` (boolean) - `store_exception` (string) - `transport_address` (string) - `weight_ranking` (number) - `primary` (boolean) - `rebalance_explanation` (string) - `remaining_delay` (string Duration) - `remaining_delay_in_millis` (DurationValueUnitMillis) - `shard` (number) - `unassigned_info` ({} UnassignedInformation) - `at` (DateTime) - `last_allocation_status` (string) - `reason` (enum UnassignedInformationReason) Values: `INDEX_CREATED`, `CLUSTER_RECOVERED`, `INDEX_REOPENED`, `DANGLING_INDEX_IMPORTED`, `NEW_INDEX_RESTORED`, `EXISTING_INDEX_RESTORED`, `REPLICA_ADDED`, `ALLOCATION_FAILED`, `NODE_LEFT`, `REROUTE_CANCELLED`, `REINITIALIZED`, `REALLOCATED_REPLICA`, `PRIMARY_FAILED`, `FORCED_EMPTY_PRIMARY`, `MANUAL_ALLOCATION` - `details` (string) - `failed_allocation_attempts` (number) - `delayed` (boolean) - `allocation_status` (string) - `note` (string) ## Code Examples #### Console ```console POST _cluster/allocation/explain { "index": "my-index-000001", "shard": 0, "primary": false, "current_node": "my-node" } ``` #### JavaScript ```javascript const response = await client.cluster.allocationExplain({ index: "my-index-000001", shard: 0, primary: false, current_node: "my-node", }); ``` #### Python ```python resp = client.cluster.allocation_explain( index="my-index-000001", shard=0, primary=False, current_node="my-node", ) ``` #### curl ```curl curl -X POST "$ELASTICSEARCH_URL/_cluster/allocation/explain" \ -H "Authorization: ApiKey $ELASTIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "index": "my-index-000001", "shard": 0, "primary": false, "current_node": "my-node" }' ``` #### Java ```java client.cluster().allocationExplain(a -> a .currentNode("my-node") .index("my-index-000001") .primary(false) .shard(0) ); ``` #### C# ```c# var response = await client.Cluster .AllocationExplainAsync(d1 => d1 .CurrentNode("my-node") .Index("my-index-000001") .Primary(false) .Shard(0) ); ``` #### PHP ```php $resp = $client->cluster()->allocationExplain([ "body" => [ "index" => "my-index-000001", "shard" => 0, "primary" => false, "current_node" => "my-node", ], ]); ``` #### Ruby ```ruby response = client.cluster.allocation_explain( body: { "index": "my-index-000001", "shard": 0, "primary": false, "current_node": "my-node" } ) ``` ## Response Examples #### Conflicting settings An example of an allocation explanation for an unassigned primary shard. In this example, a newly created index has an index setting that requires that it only be allocated to a node named `nonexistent_node`, which does not exist, so the index is unable to allocate. ```json { "index" : "my-index-000001", "shard" : 0, "primary" : true, "current_state" : "unassigned", "unassigned_info" : { "reason" : "INDEX_CREATED", "at" : "2017-01-04T18:08:16.600Z", "last_allocation_status" : "no" }, "can_allocate" : "no", "allocate_explanation" : "Elasticsearch isn't allowed to allocate this shard to any of the nodes in the cluster. Choose a node to which you expect this shard to be allocated, find this node in the node-by-node explanation, and address the reasons which prevent Elasticsearch from allocating this shard there.", "node_allocation_decisions" : [ { "node_id" : "8qt2rY-pT6KNZB3-hGfLnw", "node_name" : "node-0", "transport_address" : "127.0.0.1:9401", "roles" : ["data", "data_cold", "data_content", "data_frozen", "data_hot", "data_warm", "ingest", "master", "ml", "remote_cluster_client", "transform"], "node_attributes" : {}, "node_decision" : "no", "weight_ranking" : 1, "deciders" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index setting [index.routing.allocation.include] filters [_name:\"nonexistent_node\"]" } ] } ] } ``` #### Maximum retries An example of an allocation explanation for an unassigned primary shard that has reached the maximum number of allocation retry attempts. After the maximum number of retries is reached, Elasticsearch stops attempting to allocate the shard in order to prevent infinite retries which may impact cluster performance. ```json { "index" : "my-index-000001", "shard" : 0, "primary" : true, "current_state" : "unassigned", "unassigned_info" : { "at" : "2017-01-04T18:03:28.464Z", "failed shard on node [mEKjwwzLT1yJVb8UxT6anw]: failed recovery, failure RecoveryFailedException", "reason": "ALLOCATION_FAILED", "failed_allocation_attempts": 5, "last_allocation_status": "no", }, "can_allocate": "no", "allocate_explanation": "cannot allocate because allocation is not permitted to any of the nodes", "node_allocation_decisions" : [ { "node_id" : "3sULLVJrRneSg0EfBB-2Ew", "node_name" : "node_t0", "transport_address" : "127.0.0.1:9400", "roles" : ["data_content", "data_hot"], "node_decision" : "no", "store" : { "matching_size" : "4.2kb", "matching_size_in_bytes" : 4325 }, "deciders" : [ { "decider": "max_retry", "decision" : "NO", "explanation": "shard has exceeded the maximum number of retries [5] on failed allocation attempts - manually call [POST /_cluster/reroute?retry_failed] to retry, [unassigned_info[[reason=ALLOCATION_FAILED], at[2024-07-30T21:04:12.166Z], failed_attempts[5], failed_nodes[[mEKjwwzLT1yJVb8UxT6anw]], delayed=false, details[failed shard on node [mEKjwwzLT1yJVb8UxT6anw]: failed recovery, failure RecoveryFailedException], allocation_status[deciders_no]]]" } ] } ] } ```