Explain the shard allocations

POST /_cluster/allocation/explain

Copy endpoint

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.

Parameters

query Query Parameters

Name	Type
`index` The name of the index that you would like an explanation for.	type TypesIndexName = string
`shard` An identifier for the shard that you would like an explanation for.	number
`primary` If true, returns an explanation for the primary shard for the specified shard ID.	boolean
`current_node` Explain a shard only if it is currently located on the specified node name or node ID.	type TypesNodeId = string
`include_disk_info` If true, returns information about disk usage and shard sizes.	boolean
`include_yes_decisions` If true, returns YES decisions in explanation.	boolean
`master_timeout` Period to wait for a connection to the master node.	type TypesDuration = string \| "-1" \| "0"

Request Body

application/json

{
index?:

TypesIndexName

type TypesIndexName = string

;
shard?: number;
primary?: boolean;
current_node?:

TypesNodeId

type TypesNodeId = string

;
}

Responses

200 application/json

{
allocate_explanation?: string;
allocation_delay?:

TypesDuration

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.

type TypesDuration = string | "-1" | "0"

;
allocation_delay_in_millis?:

TypesDurationValueUnitMillis

type TypesDurationValueUnitMillis = TypesUnitMillis

;
can_allocate?:

ClusterAllocationExplainDecision

type ClusterAllocationExplainDecision = "yes" | "no" | "worse_balance" | "throttled" | "awaiting_info" | "allocation_delayed" | "no_valid_shard_copy" | "no_attempt"

;
can_move_to_other_node?:

ClusterAllocationExplainDecision

type ClusterAllocationExplainDecision = "yes" | "no" | "worse_balance" | "throttled" | "awaiting_info" | "allocation_delayed" | "no_valid_shard_copy" | "no_attempt"

;
can_rebalance_cluster?:

ClusterAllocationExplainDecision

type ClusterAllocationExplainDecision = "yes" | "no" | "worse_balance" | "throttled" | "awaiting_info" | "allocation_delayed" | "no_valid_shard_copy" | "no_attempt"

;
can_rebalance_cluster_decisions?:

ClusterAllocationExplainAllocationDecision

interface ClusterAllocationExplainAllocationDecision {
decider: string;
decision: ClusterAllocationExplainAllocationExplainDecision;
explanation: string;
}

[];
can_rebalance_to_other_node?:

ClusterAllocationExplainDecision

type ClusterAllocationExplainDecision = "yes" | "no" | "worse_balance" | "throttled" | "awaiting_info" | "allocation_delayed" | "no_valid_shard_copy" | "no_attempt"

;
can_remain_decisions?:

ClusterAllocationExplainAllocationDecision

interface ClusterAllocationExplainAllocationDecision {
decider: string;
decision: ClusterAllocationExplainAllocationExplainDecision;
explanation: string;
}

[];
can_remain_on_current_node?:

ClusterAllocationExplainDecision

type ClusterAllocationExplainDecision = "yes" | "no" | "worse_balance" | "throttled" | "awaiting_info" | "allocation_delayed" | "no_valid_shard_copy" | "no_attempt"

;
cluster_info?:

ClusterAllocationExplainClusterInfo

interface ClusterAllocationExplainClusterInfo {
nodes: { };
shard_sizes: { };
shard_data_set_sizes?: { };
shard_paths: { };
reserved_sizes: ClusterAllocationExplainReservedSize[];
}

;
configured_delay?:

TypesDuration

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.

type TypesDuration = string | "-1" | "0"

;
configured_delay_in_millis?:

TypesDurationValueUnitMillis

type TypesDurationValueUnitMillis = TypesUnitMillis

;
current_node?:

ClusterAllocationExplainCurrentNode

interface ClusterAllocationExplainCurrentNode {
id: TypesId;
name: TypesName;
roles: TypesNodeRoles;
attributes: { };
transport_address: TypesTransportAddress;
weight_ranking: number;
}

;
current_state: string;
index:

TypesIndexName

type TypesIndexName = string

;
move_explanation?: string;
node_allocation_decisions?:

ClusterAllocationExplainNodeAllocationExplanation

interface ClusterAllocationExplainNodeAllocationExplanation {
deciders?: ClusterAllocationExplainAllocationDecision[];
node_attributes: { };
node_decision: ClusterAllocationExplainDecision;
node_id: TypesId;
node_name: TypesName;
roles: TypesNodeRoles;
store?: ClusterAllocationExplainAllocationStore;
transport_address: TypesTransportAddress;
weight_ranking?: number;
}

[];
primary: boolean;
rebalance_explanation?: string;
remaining_delay?:

TypesDuration

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.

type TypesDuration = string | "-1" | "0"

;
remaining_delay_in_millis?:

TypesDurationValueUnitMillis

type TypesDurationValueUnitMillis = TypesUnitMillis

;
shard: number;
unassigned_info?:

ClusterAllocationExplainUnassignedInformation

interface ClusterAllocationExplainUnassignedInformation {
at: TypesDateTime;
last_allocation_status?: string;
reason: ClusterAllocationExplainUnassignedInformationReason;
details?: string;
failed_allocation_attempts?: number;
delayed?: boolean;
allocation_status?: string;
}

;
note?: string;
}