Explain the shard allocations

POST also GET /_cluster/allocation/explain

Get explanations for shard allocations in the cluster. 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.

Query Parameters

Request

Response

application/json

Examples

Run POST _cluster/allocation/explain to get an explanation for a shard's current allocation.

Request Console 1 / 8 languages

Console Kibana Dev Tools

POST _cluster/allocation/explain
{
  "index": "my-index-000001",
  "shard": 0,
  "primary": false,
  "current_node": "my-node"
}

JavaScript Elasticsearch JavaScript Client

const response = await client.cluster.allocationExplain({
  index: "my-index-000001",
  shard: 0,
  primary: false,
  current_node: "my-node",
});

Python Elasticsearch Python Client

resp = client.cluster.allocation_explain(
    index="my-index-000001",
    shard=0,
    primary=False,
    current_node="my-node",
)

curl Shell

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 Elasticsearch Java Client

client.cluster().allocationExplain(a -> a
    .currentNode("my-node")
    .index("my-index-000001")
    .primary(false)
    .shard(0)
);

C# Elasticsearch .NET Client

var response = await client.Cluster
    .AllocationExplainAsync(d1 => d1
        .CurrentNode("my-node")
        .Index("my-index-000001")
        .Primary(false)
        .Shard(0)
    );

PHP Elasticsearch PHP Client

$resp = $client->cluster()->allocationExplain([
    "body" => [
        "index" => "my-index-000001",
        "shard" => 0,
        "primary" => false,
        "current_node" => "my-node",
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.cluster.allocation_explain(
  body: {
    "index": "my-index-000001",
    "shard": 0,
    "primary": false,
    "current_node": "my-node"
  }
)

Response

{
  "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\"]"
        }
      ]
    }
  ]
}

Query Parameters { include_disk_info , include_yes_decisions , master_timeout , }

Request { current_node , index , primary , shard , }

Response

Query Parameters

Request