Explain the shard allocations

  • POST also GET /_cluster/allocation/explain
Auth

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

Required privileges

Cluster privileges monitor manage

Query parameters

index string

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 · default: 30s

Period to wait for a connection to the master node.

Request body

index string

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.

Response

application/json
allocate_explanation string
allocation_delay string
allocation_delay_in_millis number
can_allocate enum
Values: yes no worse_balance throttled awaiting_info allocation_delayed no_valid_shard_copy no_attempt
can_move_to_other_node enum
Values: yes no worse_balance throttled awaiting_info allocation_delayed no_valid_shard_copy no_attempt
can_rebalance_cluster enum
Values: yes no worse_balance throttled awaiting_info allocation_delayed no_valid_shard_copy no_attempt
can_rebalance_to_other_node enum
Values: yes no worse_balance throttled awaiting_info allocation_delayed no_valid_shard_copy no_attempt
can_remain_on_current_node enum
Values: yes no worse_balance throttled awaiting_info allocation_delayed no_valid_shard_copy no_attempt
configured_delay string
configured_delay_in_millis number
current_state string required
index string required
move_explanation string
primary boolean required
rebalance_explanation string
remaining_delay string
remaining_delay_in_millis number
shard number required
note string