Query parameters

  • include_disk_infoboolean

    If true, returns information about disk usage and shard sizes.

  • include_yes_decisionsboolean

    If true, returns YES decisions in explanation.

  • master_timeoutstring

    Period to wait for a connection to the master node.

    Values are -1 or 0.

application/json

Body

  • current_nodestring

    Specifies the node ID or the name of the node to only explain a shard that is currently located on the specified node.

  • indexstring
  • primaryboolean

    If true, returns explanation for the primary shard for the given shard ID.

  • shardnumber

    Specifies the ID of the shard that you would like an explanation for.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • allocate_explanationstring
    • allocation_delaystring

      A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

    • allocation_delay_in_millisnumber

      Time unit for milliseconds

    • can_allocatestring

      Values are yes, no, worse_balance, throttled, awaiting_info, allocation_delayed, no_valid_shard_copy, or no_attempt.

    • can_move_to_other_nodestring

      Values are yes, no, worse_balance, throttled, awaiting_info, allocation_delayed, no_valid_shard_copy, or no_attempt.

    • can_rebalance_clusterstring

      Values are yes, no, worse_balance, throttled, awaiting_info, allocation_delayed, no_valid_shard_copy, or no_attempt.

    • can_rebalance_cluster_decisionsarray[object]
      Hide can_rebalance_cluster_decisions attributes Show can_rebalance_cluster_decisions attributes object
    • can_rebalance_to_other_nodestring

      Values are yes, no, worse_balance, throttled, awaiting_info, allocation_delayed, no_valid_shard_copy, or no_attempt.

    • can_remain_decisionsarray[object]
      Hide can_remain_decisions attributes Show can_remain_decisions attributes object
    • can_remain_on_current_nodestring

      Values are yes, no, worse_balance, throttled, awaiting_info, allocation_delayed, no_valid_shard_copy, or no_attempt.

    • cluster_infoobject
      Hide cluster_info attributes Show cluster_info attributes object
    • configured_delaystring

      A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

    • configured_delay_in_millisnumber

      Time unit for milliseconds

    • current_nodeobject
      Hide current_node attributes Show current_node attributes object
      • idstring Required
      • namestring Required
      • rolesarray[string] Required

        Values are master, data, data_cold, data_content, data_frozen, data_hot, data_warm, client, ingest, ml, voting_only, transform, remote_cluster_client, or coordinating_only.

      • attributesobject Required
        Hide attributes attribute Show attributes attribute object
        • *string Additional properties
      • transport_addressstring Required
      • weight_rankingnumber Required
    • current_statestring Required
    • indexstring Required
    • move_explanationstring
    • node_allocation_decisionsarray[object]
      Hide node_allocation_decisions attributes Show node_allocation_decisions attributes object
      • decidersarray[object] Required
        Hide deciders attributes Show deciders attributes object
      • node_attributesobject Required
        Hide node_attributes attribute Show node_attributes attribute object
        • *string Additional properties
      • node_decisionstring Required

        Values are yes, no, worse_balance, throttled, awaiting_info, allocation_delayed, no_valid_shard_copy, or no_attempt.

      • node_idstring Required
      • node_namestring Required
      • rolesarray[string] Required

        Values are master, data, data_cold, data_content, data_frozen, data_hot, data_warm, client, ingest, ml, voting_only, transform, remote_cluster_client, or coordinating_only.

      • storeobject
        Hide store attributes Show store attributes object
      • transport_addressstring Required
      • weight_rankingnumber Required
    • primaryboolean Required
    • rebalance_explanationstring
    • remaining_delaystring

      A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

    • remaining_delay_in_millisnumber

      Time unit for milliseconds

    • shardnumber Required
    • unassigned_infoobject
      Hide unassigned_info attributes Show unassigned_info attributes object

      • atstring | number Required

        A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.

        One of:
        DateTimestringUnitMillisnumber

        Time unit for milliseconds

      • last_allocation_statusstring
      • reasonstring Required

        Values are 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, or MANUAL_ALLOCATION.

      • detailsstring
      • failed_allocation_attemptsnumber
      • delayedboolean
      • allocation_statusstring
    • notestring Generally available; Added in 7.14.0
GET /_cluster/allocation/explain
GET _cluster/allocation/explain
{
  "index": "my-index-000001",
  "shard": 0,
  "primary": false,
  "current_node": "my-node"
}
resp = client.cluster.allocation_explain(
    index="my-index-000001",
    shard=0,
    primary=False,
    current_node="my-node",
)
const response = await client.cluster.allocationExplain({
  index: "my-index-000001",
  shard: 0,
  primary: false,
  current_node: "my-node",
});
response = client.cluster.allocation_explain(
  body: {
    "index": "my-index-000001",
    "shard": 0,
    "primary": false,
    "current_node": "my-node"
  }
)
$resp = $client->cluster()->allocationExplain([
    "body" => [
        "index" => "my-index-000001",
        "shard" => 0,
        "primary" => false,
        "current_node" => "my-node",
    ],
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"index":"my-index-000001","shard":0,"primary":false,"current_node":"my-node"}' "$ELASTICSEARCH_URL/_cluster/allocation/explain"
Request example
Run `GET _cluster/allocation/explain` to get an explanation for a shard's current allocation.
{
  "index": "my-index-000001",
  "shard": 0,
  "primary": false,
  "current_node": "my-node"
}
Response examples (200)
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.
{
  "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\"]"
        }
      ]
    }
  ]
}
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.
{
  "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]]]"
        }
      ]
    }
  ]
}