What Is Split-Brain, and How Does Elasticsearch Prevent It?

What Is Split-Brain, and How Does Elasticsearch Prevent It?

A clear, step-by-step journey into the most feared failure in distributed search clusters: what happens when two parts of a cluster both believe they are in charge, and the majority-vote machinery Elasticsearch uses to make sure that never happens.

Imagine a ship crossing the ocean with a single captain. One night a thick fog splits the crew into two groups that can no longer see or hear each other. Each group waits for the captain’s orders, hears nothing, and decides to pick a new captain. By morning the ship has two captains, each steering in a different direction, each writing a different logbook, and each sure the other group has vanished. The ship is now in real danger, not because anyone was careless, but because nobody could tell the difference between “the captain is gone” and “I simply cannot hear the captain.”

That is exactly the problem computer scientists call split-brain, and Elasticsearch clusters can suffer from it if they are not designed carefully. In this tutorial we start from the very beginning: what a cluster is, why it needs a leader, and how the leader can be duplicated by accident. Then we walk through the ideas Elasticsearch uses to prevent it: majority voting, safe elections, two-step publication of changes, failure detection, careful startup rules, and a second line of defense at the level of individual data copies. By the end you will be able to explain the whole story to a teammate, design a safe cluster, and recognise the classic mistakes before they hurt you.

1The Big Picture: Clusters, Nodes and the Need for a Boss

Before we can understand a broken brain, we need to understand what a healthy one looks like.

What is an Elasticsearch cluster?

Elasticsearch is a search and analytics engine that stores documents, which are simply pieces of data such as a product description, a log line, or a customer record. Because one computer is rarely enough, Elasticsearch spreads the work across many computers that cooperate. Each running copy of Elasticsearch is called a node, and a group of nodes that share the same cluster name and work together is called a cluster. To the outside world the cluster looks like one big search engine, even though many machines are quietly working behind the scenes.

Inside the cluster, data is split into pieces called shards. Every index (a collection of related documents, roughly like a table in a database) is divided into one or more primary shards, and each primary shard can have replica shards, which are extra copies kept on other nodes. Replicas exist for two reasons: they keep the data safe if a machine dies, and they let searches run in parallel across more copies. The question that this whole tutorial revolves around is simple: who decides which node holds which shard, and who keeps that decision consistent for everybody?

Simple Analogy

Think of a class of thirty students working on a giant group project. Somebody has to keep the master seating chart, know who is absent, and decide who takes over a job when a classmate goes home sick. If every student kept their own private chart, the class would quickly descend into arguments. So the class elects one class captain who owns the official chart. In Elasticsearch, that captain is called the elected master node.

The cluster state: the official chart

The master node is responsible for lightweight but critical cluster-wide decisions: creating or deleting indices, deciding which shards live on which nodes, tracking which nodes are currently members, and recording index settings and field mappings. All of this information together is called the cluster state. Every node in the cluster keeps a copy of the latest cluster state, but only the elected master is allowed to change it. When the master makes a change, it sends the new version to the other nodes so that everybody sees the same chart.

It is important to know that the master does not handle your search requests or your document writes. Those go to data nodes and coordinating nodes. The master is more like an air traffic controller than a pilot: it does not fly any plane, but if two controllers give conflicting instructions, planes collide. This is why having exactly one master at any moment is not a nice-to-have; it is the foundation on which every other guarantee is built.

Term 1

Node

One running instance of Elasticsearch on one machine, virtual machine or container.

Term 2

Cluster

A named group of nodes that work together and present themselves as a single system.

Term 3

Master-eligible node

A node that is allowed to take part in elections and could become the elected master.

Term 4

Elected master

The single master-eligible node currently chosen to manage and change the cluster state.

Term 5

Cluster state

The shared record of nodes, indices, mappings, settings and the location of every shard.

Term 6

Primary and replica shard

A primary shard is the main copy of a slice of data; replicas are backup copies on other nodes.

Term 7

Data node

A node that stores shards and does the heavy lifting of indexing and searching.

Term 8

Voting-only node

A master-eligible node that can vote in elections but can never become the master itself.

graph TD
  M["Elected master (owns the cluster state)"]
  D1["Data node 1"]
  D2["Data node 2"]
  D3["Data node 3"]
  M -->|"sends cluster state updates"| D1
  M -->|"sends cluster state updates"| D2
  M -->|"sends cluster state updates"| D3
  C["Client"] -->|"search and write requests"| D1
        
FIG 1 — A healthy cluster: exactly one elected master, many nodes that follow it
i
Good to Know

A node can wear several hats at once, such as master-eligible and data. In small clusters that is fine. In larger, busier clusters teams usually create dedicated master-eligible nodes that do nothing else, so the “controller” is never distracted by heavy searches.

2What Exactly Is Split-Brain?

Split-brain is what happens when one cluster accidentally becomes two clusters that both think they are the real one.

A precise definition

Split-brain is a failure condition in a distributed system where a communication breakdown divides the nodes into separate groups, and more than one group elects its own leader and carries on working independently. In Elasticsearch terms, two or more nodes each believe they are the elected master of the same cluster at the same time. Each one accepts changes to the cluster state, hands out shard assignments, and tells its followers what to do. From that moment on, the cluster has two competing versions of the truth.

The name comes from a picture of a brain that has been divided into two halves that no longer talk to each other, each half acting as if it controlled the whole body. The scariest part is that nothing is technically “broken” in either half. Each half is healthy, confident and busy. The damage is invisible until the two halves try to meet again, and by then the two versions of the data may not be possible to merge.

Simple Analogy

Picture two librarians who share one library catalogue. A storm cuts the phone line between the east wing and the west wing. Each librarian keeps lending books and writing entries in a private copy of the catalogue. When the phone line comes back, the east catalogue says a rare book is on loan to Anna and the west catalogue says it was lent to Ben. Both cannot be true, and there is no automatic way to decide which librarian was right.

Why can’t a node just check if the master is dead?

This is the heart of the puzzle, and it is worth pausing on. A node that cannot reach the master has only one piece of evidence: silence. But silence has several possible causes. The master might have crashed. The master might be perfectly fine but too busy to answer for a few seconds. The network cable between the two might be cut while both are healthy. From the point of view of the lonely node, all three situations look identical. This impossibility of telling “dead” apart from “unreachable” is one of the deepest facts about distributed computing.

A naive design would say, “if I cannot reach the master for a while, I will become the master myself.” That rule feels sensible, and it is exactly what creates split-brain. Every isolated group applies the same rule and crowns its own leader. The cure cannot be to make nodes braver or faster; the cure has to be a rule that makes it mathematically impossible for two groups to both feel entitled to lead.

“Silence is not the same as death, and a system that confuses the two will eventually crown two kings.”
graph LR
  subgraph Left["Left side of the network break"]
    A1["Node A (master)"]
    A2["Node B"]
  end
  subgraph Right["Right side of the network break"]
    B1["Node C"]
    B2["Node D (new self-appointed master)"]
  end
  A1 -.-x B1
  A2 -.-x B2
        
FIG 2 — A network break leaves two groups, and a careless rule lets both keep a master

3How Split-Brain Happens in Real Life

The causes are surprisingly ordinary, which is exactly why the risk is taken so seriously.

Most people imagine dramatic events such as a data center losing power. In practice, split-brain conditions usually grow out of small, everyday problems that combine badly. Knowing the common triggers helps you see why Elasticsearch invests so heavily in prevention, and why the fixes are structural rather than a matter of “being careful.”

Cause 1

Network partitions

A switch fails, a firewall rule changes, or a link between two racks or zones drops, dividing healthy nodes into groups that cannot talk.

Cause 2

Long garbage-collection pauses

Elasticsearch runs on the Java Virtual Machine. A long memory-cleanup pause can freeze a node for many seconds, so others wrongly conclude it is gone.

Cause 3

Overloaded master nodes

A master that is also busy with heavy queries or huge aggregations may respond too slowly to health checks and lose the trust of its peers.

Cause 4

Bad configuration

Wrong quorum settings in older versions, or wrong bootstrap settings in newer ones, can let a small group decide it is the whole cluster.

Cause 5

Asymmetric network faults

Node A can reach B, B can reach C, but A cannot reach C. Nobody has the same picture of who is alive.

Cause 6

Zone or region outages

Clusters stretched over two data centers are especially exposed because the link between them is the weakest and most failure-prone part.

Simple Analogy

A garbage-collection pause is like your class captain suddenly falling asleep at the whiteboard for fifteen seconds. Nothing is wrong with the captain, but everyone in the room wonders whether they should pick a new one. If they act too fast, the captain wakes up to find that two people are now holding the marker.

The nasty case: partial connectivity

Clean partitions, where the cluster splits neatly into two groups, are actually the easy case to reason about. The truly tricky situation is partial connectivity, sometimes called a bridge or asymmetric partition. In such a case, one node in the middle can see both sides while the two sides cannot see each other. A poorly designed election process can allow both sides to be told, by different messengers, that they hold the majority. Older Elasticsearch versions were found to be vulnerable to such patterns in independent testing, which is a big reason the coordination layer was redesigned. We will meet that redesign in a few chapters.

!
Common Misconception

Many people believe split-brain only happens when the network is completely cut. In reality, slow networks, overloaded nodes and half-broken links create the same confusion. Any situation where nodes cannot agree quickly on who is alive is a candidate.

4Why Split-Brain Is So Dangerous for a Search Engine

Two masters do not just cause confusion; they cause data that cannot be repaired.

Two versions of the truth

Once two masters exist, each one manages its own group of nodes. Suppose a shard had its primary copy on a node that ended up on the left side, and its replica on a node on the right side. The right side’s master sees the primary is missing and promotes the replica to become a new primary. Meanwhile, the left side’s master still considers the old primary healthy and sees the replica missing, so it tries to build a new replica from its own nodes. Now the same shard has two primaries, each accepting different writes.

Clients keep talking to whichever nodes they can reach. One application inserts an order into the left half. Another application updates a customer record in the right half. Both receive success responses. Later the network heals and the two halves try to reunite, but they now hold two different histories for the same shards. Elasticsearch cannot simply combine them, because it has no way to know which update should win, which delete should be honored, or whether both changes were meant to coexist.

sequenceDiagram
  participant App1 as App using left side
  participant L as Left master
  participant R as Right master
  participant App2 as App using right side
  Note over L,R: Network break. Both sides elect a master.
  App1->>L: Index order 1001
  L-->>App1: Success
  App2->>R: Index order 1002
  R-->>App2: Success
  Note over L,R: Network heals. Two different histories exist.
  L-->>R: Which shard copy is the real one?
  R-->>L: Mine is. So is yours. Data will be lost.
        
FIG 3 — Both sides report success, yet the histories can never be fully merged

The kinds of damage

Silent data loss

When the halves are forced back together, one copy of a shard must be discarded in favor of the other. Every write that landed only on the discarded copy simply disappears, even though the client was told it succeeded.

Inconsistent search results

Before the reunion, users may see different results depending on which side answers them. A product might look out of stock in one region and available in another, which erodes trust quickly.

Conflicting metadata

Each master may create or delete indices and change mappings independently. After the split, the cluster may contain two incompatible definitions of the same index, which is painful to reconcile.

Endless recovery work

Even when the data can be salvaged, shards must be copied around and rebuilt. On large clusters this can mean hours of heavy network traffic and slow queries while engineers sort out what was lost.

2
masters claiming the same cluster
2
incompatible histories of the same shards
0
automatic ways to merge them safely
!
Why Prevention Beats Repair

Because the damage cannot be reliably undone, the only sensible strategy is prevention. Elasticsearch’s goal is not to detect and clean up split-brain afterwards; it is to design the rules so that a second master can never be elected in the first place.

5The Golden Rule: Only a Majority Can Lead

One simple idea from mathematics is the reason two masters can never coexist.

What is a quorum?

A quorum is the minimum number of votes needed before a decision counts. Elasticsearch uses the strictest common definition: more than half of the eligible voters. If there are three voters, you need two. If there are five voters, you need three. The magic is in the word “more than half.” Any two groups that each hold more than half of the voters must overlap by at least one voter, because there simply are not enough voters to make two separate majorities.

That overlap is what stops split-brain. A voter can only support one leader per election round. If two candidates each needed a majority, some voter would have to vote for both, which the rules forbid. So at most one candidate can ever win a given round. And a network break cannot fool the rule: the side holding fewer than half of the voters can never gather enough votes, so it simply waits, doing nothing dangerous, until it can talk to the majority again.

Simple Analogy

Imagine a class of nine students voting for captain, where a candidate needs at least five hands. If the class is split into two rooms by a locked door, one room might have five students and the other four. Only the room with five can ever choose a captain. The room with four can talk all day but has no power to decide. Nine students can never form two groups of five, so two captains are impossible.

graph LR
  subgraph Majority["Side with 2 of 3 voters: can elect"]
    N1["Master-eligible 1"]
    N2["Master-eligible 2"]
  end
  subgraph Minority["Side with 1 of 3 voters: cannot elect"]
    N3["Master-eligible 3"]
  end
  N2 -.-x N3
        
FIG 4 — With three voters, only the two-node side can keep or choose a master

The fault-tolerance table

The rule also tells us how many failures a cluster can survive. If you have n voters, you need floor(n divided by 2) plus 1 of them alive and connected. Notice the interesting pattern in the table below: adding a fourth voter to a three-voter group does not help you survive more failures, but it does increase the number of votes needed. This is why odd numbers are the standard advice.

Voting nodesVotes needed (quorum)Node failures tolerated
110
220
321
431
532
642
743
> 50%
of voters must agree for any decision
3
voters is the smallest count that survives a failure
Odd
numbers give the best value for money
i
Key Insight

The rule trades availability for safety on the small side of a partition. The minority side pauses on purpose. Elasticsearch prefers a cluster that is temporarily unable to change than one that is happily wrong.

6The Old Way: Zen Discovery and minimum_master_nodes

To appreciate the modern design, it helps to see how earlier versions handled the same problem, and why it was fragile.

How versions before 7.0 worked

In Elasticsearch 6.x and earlier, the component responsible for finding other nodes and electing a master was called Zen Discovery. Nodes pinged each other to learn who was around, and master-eligible nodes chose a master from among those they could see. To prevent split-brain, administrators had to set one important number by hand, named minimum_master_nodes. It told each node how many master-eligible nodes it must be able to see before it was allowed to take part in electing a master.

The documented advice was to set it to the number of master-eligible nodes divided by two, rounded down, plus one. With three master-eligible nodes, the setting was two. If a node saw fewer than two master-eligible nodes, including itself, it was not allowed to run an election. In theory this is the same majority rule we discussed in the last chapter. In practice, the responsibility for keeping it correct fell on humans.

1

Administrator sets the number

A person calculates the majority for the current number of master-eligible nodes and writes it into configuration on every node.

2

Cluster grows or shrinks

Someone adds two more master-eligible nodes for capacity. The right majority is now three, but the old value of two is still in force.

3

The setting silently becomes wrong

Nothing warns anyone. The cluster works perfectly, because the danger only appears during a partition.

4

A partition arrives

A group of two nodes and a group of three both satisfy the outdated threshold of two. Both elect a master, and split-brain is born.

Why this design was fragile

The trouble was not the math; it was the maintenance. The setting lived in configuration files, and every change in the number of master-eligible nodes required changing it everywhere, in the right order, sometimes through a dynamic cluster settings update while the cluster was running. A forgotten update, a copy-pasted config, or a rolling upgrade gone slightly wrong could leave a cluster quietly one partition away from disaster. Automation tools helped, but they also duplicated the mistake across every node.

There were also deeper protocol-level concerns. Independent distributed-systems testing of older versions, published around 2014 and 2015, demonstrated scenarios with unusual network failures in which data could be lost even with sensible settings. The Elasticsearch team took the lessons seriously, and that research fed into a ground-up redesign of the coordination layer.

ANTI-PATTERN-01 Avoid
Problem

Relying on a manually maintained quorum number that must be updated by people whenever the cluster changes size.

Why It’s Harmful

Human maintenance is the weak link. The setting can be wrong for months without any visible symptom, and it fails only during the rare partition when it matters most.

Correct Approach

Use a version where the cluster manages its own voting membership automatically. In modern releases this is built in, and the old setting no longer exists.

7The Modern Way: Cluster Coordination in Elasticsearch 7 and Later

Since version 7.0, Elasticsearch has managed its own majority so that humans cannot get the number wrong.

A redesigned coordination layer

Elasticsearch 7.0 introduced a completely new cluster coordination subsystem, sometimes nicknamed Zen2 to distinguish it from the earlier Zen Discovery. The design is inspired by well-known consensus ideas from computer science and was described and checked with formal modeling techniques during development. The most visible change for users is that minimum_master_nodes disappeared. The cluster now works out its own quorum, and it updates that quorum automatically as master-eligible nodes come and go.

The central concept is the voting configuration. This is the list of master-eligible nodes whose votes currently count when electing a master or approving a change to the cluster state. A decision is valid only when more than half of the nodes in the voting configuration agree. Because the voting configuration is itself stored inside the cluster state, it is protected by the same majority rule as everything else, so it cannot be changed by a minority.

Idea 1

Voting configuration

The current set of master-eligible nodes whose votes count. Elasticsearch adjusts it automatically and keeps it an odd size.

Idea 2

Term

A counter that goes up with every election attempt, so everyone can tell newer leadership from older leadership.

Idea 3

Cluster state version

A number that increases with every published change, letting nodes reject stale or out-of-order updates.

Idea 4

Pre-vote

A polite test round before a real election, checking whether an election would even have a chance of succeeding.

Idea 5

Two-phase publication

Changes are first proposed to a majority and only then committed, so no half-finished change can leak out.

Idea 6

Persistent voting records

Each node saves its term and accepted state to disk before answering, so a restart cannot make it forget a promise.

Simple Analogy

The voting configuration is like the official list of class members allowed to vote for captain. If someone joins or leaves the class, the list is updated through a vote that itself needs a majority. So nobody can secretly shrink the list to sneak in their own election.

The automatic odd-number trick

Here is a clever detail. If you run an even number of master-eligible nodes, Elasticsearch deliberately leaves one of them out of the voting configuration. Four master-eligible nodes therefore vote as three, and six vote as five. This is not wasteful; it is protective. With an even number of voters, a partition could split them exactly in half, leaving neither side with a majority and freezing the whole cluster. Removing one vote makes such an exact tie impossible and gives the same fault tolerance as the next lower odd number, at no risk.

i
Practical Meaning

Adding a fourth master-eligible node to a three-node group does not increase how many failures you can survive. It is better to go from three to five if you want extra resilience. The cluster keeps working either way, but the extra node is not buying you additional safety.

graph TD
  V["Voting configuration stored in the cluster state"]
  V --> A["Master-eligible 1: has a vote"]
  V --> B["Master-eligible 2: has a vote"]
  V --> C["Master-eligible 3: has a vote"]
  V --> D["Master-eligible 4: left out automatically"]
  A --> Q["Quorum = 2 of 3 votes"]
  B --> Q
  C --> Q
        
FIG 5 — Four master-eligible nodes, but only an odd number of votes count

8Inside an Election, Step by Step

Elections in Elasticsearch are designed to be quick, quiet, and impossible to win without a majority.

When does an election start?

A master-eligible node starts thinking about an election when it has no master, for example after startup, or after it decides its current master has failed. But it does not jump straight in. Each node waits a short, random amount of time first. The randomness is deliberate: if every node tried to become master at the same instant, they would keep splitting the votes and nobody would win. Random delays give one node a head start, and that node usually wins cleanly.

1

Detect the missing master

A node notices its master has stopped responding or that there is no master at all, and decides to consider standing for election.

2

Wait a random moment

The node pauses for a short, randomly chosen delay, so that several nodes do not all campaign in exactly the same instant.

3

Run a pre-vote

The candidate asks the other voters, “Would you vote for me if I started an election?” Voters answer honestly without changing any state. If a majority would say yes, the candidate proceeds. If not, it stops quietly.

4

Increase the term and ask for votes

The candidate raises its term number and sends real vote requests. A voter grants at most one vote per term and only if the candidate’s information is at least as fresh as its own.

5

Collect a majority

Once a majority of the voting configuration has agreed, the candidate becomes the elected master for that term.

6

Publish the first cluster state

The new master immediately publishes a cluster state stamped with its term. Followers accept it, and the cluster is back in business.

sequenceDiagram
  participant C as Candidate
  participant V1 as Voter 1
  participant V2 as Voter 2
  C->>V1: Pre-vote: would you support me?
  C->>V2: Pre-vote: would you support me?
  V1-->>C: Yes
  V2-->>C: Yes
  C->>V1: Start election at term N+1
  C->>V2: Start election at term N+1
  V1-->>C: Vote granted
  V2-->>C: Vote granted
  Note over C: Majority reached. Candidate becomes master.
  C->>V1: Publish cluster state for term N+1
  C->>V2: Publish cluster state for term N+1
        
FIG 6 — A safe election: pre-vote first, then a real vote, then the first cluster state

Why the pre-vote matters

Imagine a node that was cut off from the others by a brief network fault. During its isolation it keeps trying to start elections and keeps raising its own term number. If it then rejoined the cluster with a much higher term, the stable, healthy master would be forced to step down just because of that unrelated node’s inflated counter. The pre-vote prevents this: an isolated node cannot get a majority to say “yes” to its pre-vote, so it never raises its term, and it can reconnect without disturbing anyone.

Simple Analogy

A pre-vote is like a student quietly asking friends, “If I called for a new class election, would you actually back me?” before standing on a chair and shouting. If the friends say no, the student saves everyone the disruption and stays seated.

Why terms matter

The term is a logical clock for leadership. Any message that carries an older term than the receiver has already seen is simply ignored. That means a former master who was frozen by a long pause and then wakes up cannot cause damage. When it tries to publish a cluster state under its old term, the other nodes say, in effect, “You are yesterday’s news,” and reject it. The stale master then learns about the newer term and steps down.

i
Timing Note

Election timing settings exist so that operators can tune how long nodes wait and how often they retry. The defaults are short, fractions of a second for the random delay, because a healthy cluster should recover its master quickly. Most teams never need to change them, and changing them without a clear reason is more likely to cause trouble than solve it.

9Making Every Change Safe: Publish, Acknowledge, Commit

Winning an election is only half the story; every later change must also be approved by a majority.

The two-phase publication

Every time the cluster state needs to change, for example when an index is created or a node joins, the master follows a two-phase process. In the first phase, the master sends the proposed new state to the nodes. Each master-eligible voter checks that the proposal comes from the current term and has a sensible version number, saves it to disk, and replies with an acknowledgment. In the second phase, once a majority of the voting configuration has acknowledged, the master sends a commit message. Only then do nodes actually apply the change and start acting on it.

This ordering has a beautiful consequence. A change that reached only a minority can never be committed, because the master cannot collect enough acknowledgments. So if a master is cut off from the majority halfway through a change, that change simply fails. Nobody ever applies a half-approved decision, and no second master can later contradict something that was already committed, because the committed state is guaranteed to be stored on at least one node in every future majority.

sequenceDiagram
  participant M as Master
  participant N1 as Voter 1
  participant N2 as Voter 2
  participant N3 as Voter 3
  M->>N1: Publish new state (version 42)
  M->>N2: Publish new state (version 42)
  M->>N3: Publish new state (version 42)
  N1-->>M: Accepted and saved
  N2-->>M: Accepted and saved
  Note over M: Majority of acknowledgments reached
  M->>N1: Commit version 42
  M->>N2: Commit version 42
  M->>N3: Commit version 42
  Note over N1,N3: All nodes now apply version 42
        
FIG 7 — Two-phase publication: propose, collect a majority, then commit
Simple Analogy

Think of a school rule change. The teacher first passes a paper around asking, “Do you agree to this new rule?” Students sign only if they have read it. Once more than half have signed, the teacher announces, “The rule is now official.” If the teacher gets locked out of the room before enough signatures arrive, the rule never becomes official, and no student is told to follow it.

What if the majority does not answer in time?

If the master cannot get enough acknowledgments within a publish timeout, which defaults to a generous thirty seconds, the publication fails and the master steps down. It then goes back to being a candidate, and a new election decides whether it, or someone better connected, should lead. Followers that are too slow to keep up can also be removed from the cluster after a lag timeout, so a single sluggish node cannot hold the rest back forever.

Why saving to disk matters

Nodes write their current term and the last accepted cluster state to disk before they reply. This is essential for safety across restarts. Without it, a node could promise support to one candidate, crash, restart with no memory of the promise, and then support a second candidate in the same term. That would break the “one vote per term” rule that underlies the whole design. By persisting every promise, a restarted node remembers exactly what it agreed to.

!
Operational Warning

Because master-eligible nodes keep this vital record on disk, deleting or losing the data directory of a master-eligible node is not a harmless “reset.” The node loses its memory of past votes and may need to be treated as a brand-new member. Never copy or clone the data folder of one node onto another either, since two nodes would then share the same identity.

10Detecting Failures and What the Minority Side Does

The cluster constantly checks on itself, and the losing side of a partition behaves in a very deliberate way.

Two kinds of health checks

Elasticsearch runs two continuous fault-detection processes. The master regularly checks each follower, asking, “Are you still there?” This is called the follower check. At the same time, each follower regularly checks the master, called the leader check. By default, checks are sent about once per second, each has a timeout of around ten seconds, and a node is declared faulty after a few consecutive failures. Those numbers are configurable, but they are chosen to tolerate brief hiccups without flapping.

When the master decides a follower has failed, it removes that node from the cluster state, and shards that lived on that node get promoted or rebuilt elsewhere. When a follower decides the master has failed, it stops following, becomes a candidate, and tries to start an election through the safe process from chapter 8. Crucially, neither side can act on suspicion alone. The removal or the new election still has to be approved by a majority.

flowchart TD
  S["Node cannot reach the master"] --> P{"Can I reach a majority of voters?"}
  P -->|"Yes"| E["Run pre-vote, then election"]
  P -->|"No"| W["Stay without a master and keep retrying"]
  E --> R{"Won a majority?"}
  R -->|"Yes"| L["Become the elected master and publish state"]
  R -->|"No"| W
  W --> B["Apply the no-master block: reject writes"]
        
FIG 8 — Decision path of a node that has lost contact with its master

The no-master block

What does the minority side do while it waits? It applies a protective rule known as the no-master block. Nodes without a master cannot safely accept changes, so by default write operations are rejected, and operations that depend on the cluster state, such as creating an index, fail. Reads may continue in some cases, because searching existing shard copies does not require a master, but the results may be stale, since new writes on the other side will not be visible. An operator can choose a stricter setting that rejects everything, for use cases where stale reads are unacceptable.

This is the visible face of the safety trade-off. Users on the minority side receive errors, which is unpleasant, but they are told the truth. The alternative, quietly accepting writes that may later be discarded, would feel better in the short term and be catastrophic in the long term.

Simple Analogy

A student who cannot reach the class captain and cannot gather a majority of classmates must put the pencil down. They can still read the chart on the wall, but they cannot change it. It is frustrating, yet far better than scribbling changes that will be crossed out later.

i
Design Lesson

Elasticsearch chooses consistency over availability on the minority side of a partition. This is the classic trade-off described by the CAP idea: when the network breaks, you cannot have both perfect agreement and full availability, and the coordination layer picks agreement.

11Starting Safely: Discovery, Bootstrapping and the Cluster Identity

A brand-new cluster has no history to lean on, so the very first election needs special care.

Discovery: how nodes find each other

Before any election, nodes must find one another. In modern versions this is controlled by a list of seed hosts, addresses of other nodes that a starting node should contact to learn who else is in the cluster. Nodes exchange lists of the peers they know about, and quickly build a complete picture. Discovery only helps nodes meet; it does not by itself make anybody a master. Elections still follow the voting rules above.

The bootstrapping problem

When a brand-new cluster starts for the very first time, there is no voting configuration yet, so no majority can be computed. Somebody must say who the founding voters are. This is the job of the initial master nodes setting. It lists the master-eligible nodes that will form the first voting configuration, so that the very first election has a clear definition of “majority.” The setting is needed only once, when the cluster first forms. After that, the cluster manages its own voting configuration.

Simple Analogy

On the very first day of a new school year, nobody has a class list yet. The teacher reads out the founding names, and from then on the class manages its own membership. The founding list is only used on day one. Reading it out every morning for the rest of the year would just cause confusion.

The cluster UUID: a birth certificate

When a cluster elects its first master, it gets a unique identifier, the cluster UUID, which is saved in the cluster state on every member. A node that has already joined one cluster remembers that UUID, and it refuses to join a different cluster with a different UUID. This protects against a subtle form of split-brain: two groups of freshly started nodes that each bootstrapped separately and accidentally ended up as two independent clusters with the same name. Once formed, they cannot merge by accident, because each would reject the other’s identity.

ANTI-PATTERN-02 Avoid
Problem

Leaving the initial master nodes setting in place permanently, or using it on a node that is meant to join an already-running cluster.

Why It’s Harmful

The setting is a bootstrapping instruction. If a node with a wiped data folder starts with it, the node may try to form a brand-new cluster of its own instead of joining the existing one, producing exactly the two-cluster situation we want to avoid.

Correct Approach

Use it only for the first start of a new cluster, on the founding master-eligible nodes, with identical values. Remove it once the cluster has formed, and never set it on nodes that join later.

!
Common Mistake

Starting two separate groups of nodes with the same cluster name but different bootstrap settings, for example in two data centers, and then connecting them later. They will not merge; they will each insist on their own identity. Plan the founding voters once, in one place, before the first start.

i
Development Shortcut

For a single-machine laptop setup, Elasticsearch offers a single-node discovery mode that skips the founding-voters ceremony entirely. It is convenient for experiments, but it is not a way to build a resilient production cluster.

12Sizing Master Nodes: One, Two, Three and Beyond

The number of master-eligible nodes, and where you place them, decides how much failure the cluster can absorb.

Walking through the options

One master-eligible node

Simple and free of split-brain, because there is nobody to disagree with. But it is a single point of failure: if that node stops, the cluster cannot elect anyone. Suitable for development and small, non-critical setups.

Two master-eligible nodes

This is the trap. With two nodes, a majority means both. Elasticsearch will let only one of them hold a vote, so losing that particular node stops the cluster, and you have gained no real resilience over a single node. If you truly only have two machines, it is usually better to make just one master-eligible, or add a small third voter.

Three master-eligible nodes

The standard, recommended minimum for a highly available cluster. Any one node can fail, and the other two still form a majority. Most production clusters start here, and many never need more.

Five or more master-eligible nodes

Lets you survive two simultaneous failures, for example one node in maintenance while another crashes. More voters also means more messages per decision, so very large numbers add overhead without adding much benefit. Five is a common upper choice for critical systems.

Even numbers such as four or six

They work, because Elasticsearch leaves one node out of the vote automatically, but you pay for a machine that adds no extra failure tolerance. Prefer the next odd number.

Voting-only nodes: a cheap tie-breaker

Sometimes you have exactly two comfortable locations for full-sized machines and want a third vote without buying a third large server. Elasticsearch offers voting-only nodes for this purpose. A voting-only node takes part in elections and in approving cluster state changes, but it can never be elected master itself, so it can be small and cheap. It acts as the deciding vote in the classic two-location setup.

Simple Analogy

Two teams of equal size compete for a decision. Bringing in one neutral referee who does not play, but whose opinion counts when the teams disagree, guarantees that a decision can always be reached. A voting-only node is that referee.

Spreading across zones

Placing all master-eligible nodes in one rack or zone means one failure can remove the whole majority. Cloud teams therefore spread masters across three availability zones, one node in each. Losing a whole zone then removes only one vote, and the other two still form a majority. With only two zones, no arrangement can survive the loss of the zone that holds the majority. This is why a small third location, even hosting just a voting-only tie-breaker, is such a valuable addition.

LayoutLoses a whole zone?Verdict
3 masters in 1 zoneNo, cluster stopsWeak
2 masters in each of 2 zones (4 total, 3 vote)Only if the smaller-voting zone failsRisky
1 master in each of 3 zonesYes, 2 of 3 remainRecommended
1 master in each of 2 zones plus voting-only tie-breaker in a thirdYes, 2 of 3 remainGood and economical

13The Second Line of Defense: Protecting Individual Shards

Even below the level of the master, Elasticsearch adds safeguards so that a stale copy of data cannot quietly win.

Primary terms

Every primary shard has a primary term, a counter that increases each time a replica is promoted to become the new primary. Every write operation carries the primary term of the shard copy that produced it. Replica shards remember the highest term they have seen, and they reject any operation that arrives with an older term. So if an old primary somehow keeps running after it has been replaced, its write attempts to the replicas will be refused, because those replicas already know about the newer primary.

Simple Analogy

Imagine a notebook where every entry is stamped with the number of the current note-taker. After a new note-taker is chosen, the class refuses any entry stamped with the old number. A former note-taker who is slow to realise they were replaced can scribble as much as they like, but nobody will accept it.

Sequence numbers and checkpoints

Each operation on a shard also receives a sequence number, an ever-increasing counter that gives writes a definite order. Elasticsearch tracks a global checkpoint, which is the highest sequence number that every in-sync copy is known to have processed. If a replica falls behind or a primary fails, this bookkeeping lets Elasticsearch work out exactly which operations are missing and replay just those, rather than copying an entire shard.

In-sync copies

The master keeps, inside the cluster state, a list of which shard copies are in sync. Only an in-sync copy is allowed to be promoted to primary, so a copy that missed writes cannot become the authority. Because this list lives in the cluster state, it is protected by the same majority rule discussed earlier. A minority side cannot edit it.

sequenceDiagram
  participant OP as Old primary (term 3)
  participant R as Replica promoted to primary (term 4)
  participant RR as Other replica
  Note over OP,R: Old primary is isolated. Replica is promoted.
  R->>RR: Write with term 4
  RR-->>R: Accepted
  OP->>RR: Write with term 3
  RR-->>OP: Rejected: newer term already seen
  Note over OP: Old primary learns it was replaced and stops
        
FIG 9 — Stale primaries are refused because replicas remember the latest primary term
!
Honest Limitation

A primary that has just been cut off may briefly keep accepting writes until it discovers the problem, typically when it fails to contact its replicas or its leader check fails. Writes that it never manages to replicate are not acknowledged as safely stored, and they are discarded when the copy is reconciled. The window is small, but it is a reminder that shard-level safety complements, and does not replace, the quorum rule at the master level.

14Operating Safely: Changing, Restarting and Recovering the Cluster

Most real-world outages come not from clever attacks but from well-meaning maintenance done in the wrong order.

Adding master-eligible nodes

Adding nodes is straightforward. Start the new master-eligible nodes with the correct discovery information, and they join the cluster and are added to the voting configuration automatically. You should not set the bootstrapping setting on them. Add them gradually, one or two at a time, letting the cluster settle between changes.

Removing master-eligible nodes

Removing nodes is where care is needed. Elasticsearch adjusts the voting configuration automatically when you stop master-eligible nodes one at a time, and it waits for each change to be safely committed before the next. Removing a small number at a time is safe. But removing half or more of the master-eligible nodes at once, before the voting configuration has adapted, can strand the remaining nodes without a majority. For those larger changes, operators use the voting exclusions feature, which tells the cluster in advance to stop counting specific nodes as voters so it can shrink safely.

1

Plan the target size

Decide how many master-eligible nodes should remain, ideally an odd number of at least three, and never fewer than the number needed for the workload’s resilience.

2

Exclude the leaving voters

If you are removing many at once, register the leaving nodes as voting exclusions so the voting configuration shrinks first.

3

Confirm the new voting set

Check that the cluster state now lists only the intended voters and that a master is elected and stable.

4

Stop the nodes and clean up

Shut down the leaving nodes, then clear the exclusions so they do not linger and cause surprises later.

Rolling restarts and upgrades

During maintenance, restart master-eligible nodes one at a time, and wait until the cluster reports a healthy state and an elected master before touching the next. Restarting two of three masters together temporarily removes the majority and pauses cluster changes. In managed environments such as Kubernetes operators or cloud services, this discipline is usually automated, but understanding why it exists helps you troubleshoot when automation misbehaves.

When the majority is permanently lost

If a majority of master-eligible nodes are permanently destroyed, for example after a disaster, the cluster cannot elect a master by itself, because the survivors do not hold a majority of the old voting configuration. Elasticsearch ships with last-resort command-line tools that let an administrator deliberately override the safety rules on the surviving nodes to form a new cluster. These tools can discard data and are meant to be used only after every other option has failed, ideally with support from the vendor or an experienced engineer and with backups in hand.

!
Last Resort

Overriding the majority rule deliberately creates the very situation the rule was built to avoid: a new cluster identity that ignores what the lost nodes may have known. Use it only when the lost nodes are truly gone forever, never when they are merely unreachable, or you will manufacture a split-brain by hand.

ANTI-PATTERN-03 Avoid
Problem

Shutting down several master-eligible nodes at the same time during maintenance, or removing half of them in one step.

Why It’s Harmful

The remaining nodes may no longer hold a majority of the current voting configuration, so the cluster freezes and cannot elect a master until enough nodes return.

Correct Approach

Change master-eligible membership gradually, use voting exclusions for larger reductions, and always confirm a healthy elected master before proceeding to the next step.

15Security, Monitoring and Metrics

A cluster that is safe on paper still needs to be watched, and protected from nodes that should not be there.

Security considerations

Split-brain is usually accidental, but the same coordination channel is a sensitive target. Modern Elasticsearch enables security features by default, including encrypted and authenticated communication between nodes. This matters because the master-election messages travel over the internal transport layer. Encrypting that layer and requiring certificates means a stray or malicious machine on the network cannot simply announce itself as a node, join the voting, or inject a false cluster state.

Good network hygiene matters too. Keep the internal transport ports reachable only by other cluster members, use firewalls and security groups that do not change accidentally during deployments, and avoid exposing nodes directly to the internet. A firewall change that blocks traffic between two zones is one of the most common real-world causes of partitions, so treat those rules as production-critical configuration.

What to monitor

Signal 1

Elected master identity

Track which node is master. Frequent changes suggest network trouble, overloaded nodes, or long pauses.

Signal 2

Cluster health colour

Green, yellow and red show whether primaries and replicas are allocated. A sudden change often follows a partition.

Signal 3

Node count

An unexpected drop in the number of nodes seen by the master is an early warning of connectivity problems.

Signal 4

JVM heap and pause times

Long garbage-collection pauses are a leading cause of nodes being wrongly declared dead.

Signal 5

Pending cluster tasks

A growing queue of tasks at the master means it cannot keep up with changes and may soon miss its own deadlines.

Signal 6

Log messages

Messages about the master not being discovered, nodes leaving, or publication timeouts are direct evidence of coordination trouble.

Operators typically look at the cluster health endpoint, the list of nodes and their roles, the current master, and allocation explanations for shards that fail to assign. Dashboards built on these signals, with alerts for master changes and for any period without a master, catch most problems before users notice. Alert on the cause, such as long pauses or lost nodes, rather than only on the symptom, such as red status.

1
elected master at any moment
3
master-eligible nodes for real resilience
3
zones for surviving a zone outage
i
Heap Advice

Keep the Java heap within recommended limits, generally no more than half of the machine’s memory and below the threshold at which the JVM loses its memory-pointer optimisations. A well-sized heap reduces long pauses, which in turn reduces false failure alarms and needless elections.

16Design Patterns and Anti-Patterns

Experience from many production clusters has produced a handful of habits worth copying and a handful worth avoiding.

Patterns worth adopting

Dedicated master-eligible nodes

In clusters of meaningful size, keep three master-eligible nodes that do only cluster management. They need modest hardware, but they need to be reliable and unburdened by heavy queries.

Three-zone placement

Put one master-eligible node in each of three zones. A zone outage then removes one vote, and the cluster keeps its majority.

Voting-only tie-breaker

When only two locations host the big machines, add a small voting-only node in a third place, so a decision is always possible.

Replicas and shard allocation awareness

Spread replicas across zones so that losing a zone does not remove every copy of a shard, and pair that with a healthy master majority.

Snapshots to remote storage

Regular snapshots are the ultimate safety net. If something goes wrong beyond the reach of the coordination rules, you can restore from a known-good copy.

Anti-patterns to avoid

ANTI-PATTERN-04 Avoid
Problem

Running exactly two master-eligible nodes and assuming this provides high availability.

Why It’s Harmful

A majority of two is two, and Elasticsearch counts only one of them as a voter to avoid ties. Losing the voting node halts the cluster, so you get extra cost without extra safety.

Correct Approach

Use three master-eligible nodes, or two full nodes plus a small voting-only tie-breaker.

ANTI-PATTERN-05 Avoid
Problem

Making busy data nodes serve as master-eligible nodes in a large, heavily loaded cluster.

Why It’s Harmful

Heavy searches and indexing cause long pauses and slow responses. Peers may judge the master unhealthy, triggering needless elections and instability.

Correct Approach

Separate the roles so the master’s only job is coordination, and size its memory and CPU for steady, predictable work.

ANTI-PATTERN-06 Avoid
Problem

Cloning a node by copying its data directory to a new machine, or restoring an old machine image and starting it beside the original.

Why It’s Harmful

Two nodes share one identity and one voting history. The cluster cannot tell them apart, which breaks the assumptions behind the majority rule.

Correct Approach

Start new nodes with empty data directories and let them join normally, or restore data through the supported snapshot process.

ANTI-PATTERN-07 Avoid
Problem

Stretching a cluster across two distant data centers with equal numbers of master-eligible nodes and no third location.

Why It’s Harmful

The link between the sites is the most likely thing to fail, and when it does, neither site may hold a majority, or the wrong one may.

Correct Approach

Use a third location for a tie-breaker, or run independent clusters in each site and replicate between them using a cross-cluster feature instead of stretching one cluster.

17Advantages, Disadvantages and Trade-offs of the Majority Approach

No design is free. Understanding what the majority rule costs helps you decide where to spend effort.

Advantages

  • Mathematically prevents two masters from being elected at the same time
  • Voting configuration is managed automatically, removing a whole class of human error
  • Stale masters and stale primaries are rejected using terms and versions
  • Committed changes cannot be lost, because every future majority contains a node that saw them
  • Cluster identity checks stop accidental merging of independently formed clusters

Disadvantages / Trade-offs

  • The minority side of a partition becomes read-limited and rejects writes
  • You need at least three master-eligible nodes to survive even one failure
  • Stretching across only two locations cannot be fully resilient without a tie-breaker
  • Losing a majority permanently forces risky manual recovery
  • Extra voters add small coordination overhead to every cluster state change

Older and newer approaches side by side

AspectBefore 7.0 (Zen Discovery)7.0 and later
Quorum settingSet by hand and updated by humansManaged automatically by the cluster
Risk of wrong quorumHigh during resizingRemoved as a category
Election processPing-based, less formalTerm-based with pre-vote and majority voting
Cluster state changesLess strict about commit rulesTwo-phase publish and commit with majority
BootstrappingImplicit through discoveryExplicit founding voters on first start
Even numbers of mastersCould create tied votesOdd voting set enforced automatically
i
How to Think About It

The cost of the majority rule is small and predictable: some downtime on the losing side. The cost of split-brain is large and unpredictable: lost data and long recovery. Engineers almost always choose the small, predictable cost.

18Real-World and Industry Examples

The same principles show up wherever teams run Elasticsearch, or its relatives, at scale.

E-commerce search

An online store powers product search and filters with Elasticsearch. Running three dedicated masters across three zones lets the shop keep serving searches and updating stock even when one zone has an outage, and avoids the horror of two catalogues with different prices.

Centralised logging and observability

Companies push huge volumes of application logs into Elasticsearch for troubleshooting. Because logs arrive constantly, a stable master matters: if coordination stalls, ingestion pipelines back up. Dedicated masters keep heavy ingestion from starving the coordination layer.

Security analytics

Security teams search events for signs of attacks. Losing or duplicating events because of a split cluster would create blind spots, so these deployments favor conservative topologies, replicas in multiple zones, and frequent snapshots.

Managed cloud services

Managed offerings from Elastic and from cloud providers commonly place dedicated master nodes across multiple availability zones by default or by recommendation, precisely to give customers the three-zone majority pattern without manual work. Related search engines derived from Elasticsearch, such as OpenSearch, follow similar advice about three dedicated masters.

Kubernetes deployments

Operators that run Elasticsearch on Kubernetes coordinate restarts so that only one master-eligible pod is restarted at a time and voting exclusions are handled for shrinking. They automate exactly the careful maintenance steps described earlier.

“The best split-brain incident is the one that never happens because the boring rules were followed.”

The same idea beyond Elasticsearch

Majority voting is not unique to Elasticsearch. Coordination systems such as ZooKeeper and etcd, and many distributed databases, rely on the same principle. Learning it here gives you a mental model that transfers to almost any system that must keep several machines in agreement. When you next meet a new distributed tool, ask the same three questions: how many voters, what counts as a majority, and what happens to the side without one.

19Frequently Asked Questions

Short answers to the questions beginners ask most often.

Q1Can split-brain still happen in Elasticsearch 7 and later?

With the built-in coordination layer and sensible topology, two masters cannot be elected under normal operation, because every election and change needs a majority of the voting configuration. The remaining risks come from human actions that override the rules, such as cloning nodes, misusing bootstrap settings, or using last-resort recovery tools carelessly.

Q2Do I still need to set minimum_master_nodes?

No. In modern versions the setting has been removed, and the cluster computes and updates its own quorum. If you are still running a very old version that uses it, plan an upgrade, because manual quorum management is a well-known source of risk.

Q3Why are three master-eligible nodes recommended instead of two?

Because two provides no additional fault tolerance. A majority of two is both nodes, and Elasticsearch uses only one as a voter to avoid ties. Three lets any single node fail while the other two still form a majority.

Q4Is a bigger number of master-eligible nodes always better?

No. Beyond five, extra voters mostly add coordination overhead. Choose the number based on how many simultaneous failures you must survive, and keep it odd.

Q5What happens to my searches on the minority side of a partition?

Nodes there have no master, so operations that change cluster state and, by default, writes are rejected. Some searches on existing shard copies can still succeed, but results may be out of date. You can choose a stricter behavior if stale reads are unacceptable.

Q6What is a voting-only node and when should I use it?

It is a master-eligible node that votes but can never become the master. It is ideal as a small, cheap tie-breaker, especially when you have big machines in two locations and want a third vote in a separate place.

Q7Does the initial master nodes setting need to stay in my configuration?

No. It is only for bootstrapping a brand-new cluster on its first start. Afterwards it should be removed, and it should never be set on nodes joining an existing cluster.

Q8Can two Elasticsearch clusters with the same name merge if they are connected?

No. Each cluster has a unique identifier assigned when it first forms, and nodes that belong to one cluster refuse to join another cluster with a different identifier. This prevents accidental merging.

Q9Do long garbage-collection pauses really cause elections?

Yes, they can. A node frozen for longer than the health-check tolerance may be declared failed, and if that node was the master, a new election follows. Proper heap sizing and dedicated master nodes reduce this risk.

Q10What should I do if I lose most of my master-eligible nodes permanently?

First try to bring the missing nodes back. If they are truly gone, use the documented last-resort recovery tools with great care, after taking backups of the surviving data. Expect that some recent changes may be lost, and consider involving experienced support.

Q11Does having replicas protect me from split-brain?

Replicas protect against losing data when nodes fail, but they do not prevent a second master. Preventing split-brain is the job of the majority rule. The two work together: the majority rule keeps the cluster consistent, and replicas keep copies available.

Q12Is single-node mode safe for production?

It cannot suffer split-brain because it has no peers, but it has no resilience either. If that node fails, everything stops. It is meant for development and simple experiments.

20Summary and Key Takeaways

Split-brain is what happens when a communication failure lets two groups of nodes both elect a leader and carry on independently, producing two incompatible versions of the truth. Because a node cannot tell a dead master from an unreachable one, the only reliable cure is a rule that makes two leaders mathematically impossible. Elasticsearch applies that rule through majority voting over a voting configuration that the cluster maintains by itself, backed by terms, pre-votes, two-phase publication, persistent voting records, failure detection, a protective no-master block, careful bootstrapping, cluster identity checks, and shard-level primary terms. Combined with a sensible topology of three master-eligible nodes across three zones, these mechanisms turn a frightening failure into a boring non-event.

Key Takeaways

  • Split-brain means two masters — a network or health problem lets separate groups each elect a leader, creating conflicting histories that often cannot be merged.
  • Majority is the cure — any decision needs more than half of the voting configuration, and two majorities can never exist at once.
  • Modern versions manage the quorum for you — since 7.0 the voting configuration adjusts automatically, and the old manual quorum setting is gone.
  • Elections and changes are guarded — terms, pre-votes, two-phase publication and persisted votes stop stale or partial decisions from taking effect.
  • Use three master-eligible nodes across three zones — or two full nodes plus a small voting-only tie-breaker; avoid exactly two masters and avoid even numbers.
  • Protect the bootstrap and the data directory — use the initial master setting only on a first start, never clone nodes, and treat last-resort recovery tools as dangerous.
  • Watch and maintain calmly — monitor master changes, pauses and node counts, change master membership gradually, and keep snapshots as your final safety net.