The cluster.initial_master_nodes setting lists the master-eligible nodes that form the initial voting configuration when a brand-new Elasticsearch cluster starts for the first time. It has no default value and must be set explicitly on every master-eligible node during initial bootstrap of a multi-node cluster. Once the cluster has elected a master and persisted its voting configuration to disk, this setting must be removed - leaving it in place after bootstrap is a source of split-brain risk and confusing failure modes.
What This Setting Does
Elasticsearch 7.0 replaced the older discovery.zen.minimum_master_nodes quorum with an auto-managed voting configuration. To start a fresh cluster, Elasticsearch needs to know which nodes can vote in the first master election. That seed list is cluster.initial_master_nodes. From the second restart onwards, the persisted voting configuration on disk takes over, and the setting is ignored (and warned about in the logs).
Default and Allowed Values
| Property | Value |
|---|---|
| Default | None - must be set explicitly for new multi-node clusters |
| Type | List of strings (node names or transport addresses), static |
| When required | First start of a multi-node cluster with master-eligible nodes |
| When forbidden | Existing clusters, single-node bootstrap with discovery.type: single-node, adding nodes to a live cluster |
For a single-node development cluster (discovery.type: single-node), do not set this. For any multi-node production cluster, set it once at first bootstrap.
How to Set It
In elasticsearch.yml on every master-eligible node, before the very first start:
# Bootstraps the initial voting configuration for a brand-new cluster.
# REMOVE this setting after the cluster has successfully formed.
cluster.initial_master_nodes:
- es-master-01
- es-master-02
- es-master-03
The values must match each node's node.name (or, less commonly, its publish address). The list must be identical on every master-eligible node - a mismatch can let two subsets of nodes bootstrap independently, which is the split-brain scenario the setting exists to prevent.
For an odd quorum size (3 or 5), list every master-eligible node. Even sizes (2, 4) are not recommended because they tolerate the same number of failures as the next-lower odd number while doubling the network cost.
After Bootstrap: Remove the Setting
The Elasticsearch reference docs are explicit: remove cluster.initial_master_nodes from every node's elasticsearch.yml after the cluster has formed. The persisted cluster state already knows the voting configuration; the setting is now stale and can cause incorrect bootstrap if the data directory is ever wiped on a quorum of nodes.
Procedure:
- Confirm the cluster is healthy and has a stable master:
GET /_cluster/healthandGET /_cat/master. - Edit
elasticsearch.ymlon each master-eligible node and delete thecluster.initial_master_nodesblock. - Roll the restart one node at a time so the cluster stays available.
Operational Impact
A correct bootstrap value gives you a deterministic first master election. Incorrect or inconsistent values produce these failure modes:
- Two independent clusters from one intended one. If two nodes have non-overlapping
cluster.initial_master_nodeslists, both can bootstrap independently. They then refuse to merge. - No election at all. If the listed nodes are not actually started or are unreachable, the cluster sits in a yellow/red state with no elected master and the log line
master not discovered or elected yet. - Mismatched names. A name listed in
cluster.initial_master_nodesthat does not equal any node'snode.nameis ignored, which can drop the effective quorum below the minimum needed to elect a master.
Common Mistakes
- Leaving the setting after bootstrap. Strip it on the first rolling restart.
- Setting it on every node in an existing cluster. Reusing the bootstrap setting when adding a node to a live cluster does nothing useful and creates a misleading log noise level.
- Listing only one or two nodes when more are master-eligible. Use the full set of master-eligible nodes you actually intend to vote in the first election.
- Using addresses that change between starts. Prefer
node.nameover IP addresses for stability. - Setting it together with
discovery.type: single-node. Pick one - they are mutually exclusive.
Prevent initial_master_nodes Misconfiguration with Pulse
Pulse is an AI DBA for Elasticsearch and OpenSearch that tracks cluster.initial_master_nodes and the voting configuration state across master-eligible nodes, flagging:
- Drift between nodes: lists that disagree between master-eligible peers (the split-brain risk this setting exists to prevent)
- Settings that are unsafe for your workload (e.g.
cluster.initial_master_nodesstill present after the cluster has formed and persisted its voting configuration; values that do not match any node'snode.name; even-sized lists like 2 or 4) - The downstream operational impact:
master not discovered or elected yetlog entries, master GC pressure on undersized quorums, and a stale bootstrap setting that could let a wiped cluster re-bootstrap with the wrong voting configuration
After bootstrap, Pulse alerts when the setting was not removed - the most common production hygiene miss on this setting.
Frequently Asked Questions
Q: What is cluster.initial_master_nodes used for in Elasticsearch?
A: cluster.initial_master_nodes lists the master-eligible nodes that form the initial voting configuration when a new multi-node Elasticsearch cluster starts for the first time. After the cluster forms, the persisted voting configuration takes over and the setting is no longer used.
Q: Do I need cluster.initial_master_nodes for a single-node cluster?
A: No. For a single-node cluster, set discovery.type: single-node in elasticsearch.yml instead. Elasticsearch will form the cluster automatically without cluster.initial_master_nodes.
Q: How many nodes should I list in cluster.initial_master_nodes?
A: List every master-eligible node you intend to have in the initial cluster, typically 3 in production. Use an odd number so quorum math works cleanly; 2 or 4 nodes tolerate the same failures as 1 or 3 with extra cost.
Q: Can I use cluster.initial_master_nodes to add a new node to an existing cluster?
A: No. Adding a new node uses discovery.seed_hosts to find the existing cluster. cluster.initial_master_nodes only takes effect at the very first start of a brand-new cluster and is ignored once a voting configuration is persisted to disk.
Q: What happens if I forget to remove cluster.initial_master_nodes after bootstrap?
A: The cluster continues to operate, and Elasticsearch logs a warning. The risk is that if every node's data directory is later wiped, the stale setting could let the cluster re-bootstrap with the wrong voting configuration. Remove it on the first scheduled rolling restart.
Q: Should I use node names or IP addresses in cluster.initial_master_nodes?
A: Use node.name values. They are stable across IP changes (containers, DHCP, replacements). Make sure each node's node.name in elasticsearch.yml matches what you put in the list - they are case-sensitive.
Q: What's the best tool to prevent split-brain from cluster.initial_master_nodes misconfiguration?
A: Pulse is built for this. It is an AI DBA for Elasticsearch and OpenSearch that compares cluster.initial_master_nodes lists across master-eligible peers, alerts when the setting is left behind after bootstrap, and flags mismatched node names that would silently lower the effective quorum.
