Elections and Automatic Failover
Learners will simulate a primary failure and observe the election algorithm that promotes a secondary, keeping downtime under 10 seconds.
Elections and Automatic Failover is a free MongoDB Academy lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the MongoDB Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Why Automatic Failover Matters
Automatic failover is the ability of a MongoDB replica set to recover from a primary node failure without human intervention. When the primary becomes unreachable, the remaining members automatically elect a new primary — typically within 10 to 30 seconds — so that applications experience only a brief pause rather than a full outage.
Heartbeats: Detecting Failures
Replica set members continuously exchange heartbeat messages every 2 seconds. If a member does not receive a heartbeat response within electionTimeoutMillis (default 10 seconds), it marks the silent member as inaccessible. If the missing member is the primary, the remaining eligible members begin an election.
// Check heartbeat interval and election timeout in replica set config
rs.conf().settings.heartbeatIntervalMillis // 2000 ms
rs.conf().settings.electionTimeoutMillis // 10000 msTriggering an Election
An election is triggered in three scenarios: 1) the primary becomes unreachable (network partition or crash), 2) a user manually steps down the primary with rs.stepDown(), or 3) a secondary with higher priority joins and the current primary has lower priority. Only members with votes: 1 and priority > 0 are eligible to become the new primary.
// Manually step down the current primary (useful for maintenance)
rs.stepDown(60) // yield primary for at least 60 secondsRaft-Inspired Consensus Protocol
MongoDB elections use a protocol inspired by Raft consensus. Each candidate increments its term counter and solicits votes from other members. A candidate wins if it receives votes from a majority of the voting members. The candidate with the most up-to-date oplog (highest optime) is preferred — this prevents data loss by ensuring the new primary has seen all acknowledged writes.
// Inspect the term number and optime of all members
rs.status().members.forEach(m => {
print(m.name, 'term:', m.configTerm, 'optime:', m.optimeDate)
})Majority Vote Requirement
A candidate needs votes from more than half of all voting members (not just the ones currently reachable). In a 3-member set with 3 votes, a majority is 2. This means that if 2 members go down simultaneously, the surviving member cannot elect itself — it would be operating on stale data with no way to know if the other two members have newer writes.
// With 3 members:
// majority = floor(3/2) + 1 = 2
// If only 1 member survives, it cannot elect itself
// The set becomes read-only until connectivity is restoredThe Election Process Step by Step
The election unfolds as follows: 1) A secondary notices the primary is gone after the timeout. 2) It transitions to CANDIDATE state. 3) It sends RequestVote messages to all other members. 4) Members grant votes if the candidate's oplog is at least as current as theirs and they haven't already voted. 5) The winner transitions to PRIMARY and begins accepting writes.
Write Unavailability During Election
During the election window (typically a few seconds), writes are refused because there is no primary. The MongoDB driver buffers write operations and retries them once a new primary is elected. With retryable writes enabled (the default in modern drivers), transient election errors are transparently retried once.
// Retryable writes are enabled by default in the connection string
const client = new MongoClient(
'mongodb+srv://host/db?retryWrites=true'
)Priority and Election Preference
When multiple candidates are equally up to date, priority breaks the tie — the member with the highest priority wins. If a secondary with higher priority rejoins after being offline, it will trigger a new election to take the primary role. Setting priority to 0 permanently excludes a member from ever becoming primary.
// Boost priority on the preferred primary node
let cfg = rs.conf()
cfg.members[0].priority = 2 // preferred
cfg.members[1].priority = 1
cfg.members[2].priority = 1
rs.reconfig(cfg)Network Partition Scenarios
In a network partition, members on one side of the split cannot communicate with the other. The side with the majority of votes can elect a primary; the minority side enters a read-only state. This prevents a split-brain scenario where two members simultaneously believe they are primary and accept conflicting writes.
Monitoring Failover Events
You can monitor elections and failovers by examining the MongoDB log or querying the system.replset config. Atlas provides real-time alerts for election events. In your application logs, you will see MongoNotPrimaryError or MongoNetworkError spikes during an election — retryable writes handle these automatically.
// Check the number of elections in the current status
rs.status().electionHighestObservedTime
// Or watch change streams on 'admin.$cmd' for electionId changesKeeping Failover Fast: Best Practices
To minimise failover time: 1) Keep replica sets with odd member counts (3 or 5) to avoid needing arbiters. 2) Use a majority write concern to ensure the elected secondary has all committed writes. 3) Minimise oplog lag by providing sufficient oplog size. 4) Place replica set members in the same region for low-latency heartbeats.
// Increase oplog size at runtime (requires 4.4+)
db.adminCommand({ replSetResizeOplog: 1, size: 16384 })
// size in MB — 16 GB is suitable for busy clustersQuick Check
Test your understanding of MongoDB & NoSQL Databases concepts from this lesson.
Lesson Recap
In this lesson you learned: heartbeats detect primary failure within electionTimeoutMillis (10 s default), the candidate with the most current oplog and highest priority wins the election, and retryable writes let applications survive brief election windows transparently. Next up we explore write concerns and how to control the durability of writes across the replica set.
Frequently asked questions
Is the “Elections and Automatic Failover” lesson free?
Yes — the full text of “Elections and Automatic Failover” is free to read here on the web, and the MongoDB Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the MongoDB Academy course, upgrade to CoddyKit PRO.
What will I learn in “Elections and Automatic Failover”?
Learners will simulate a primary failure and observe the election algorithm that promotes a secondary, keeping downtime under 10 seconds. You practise MongoDB Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start MongoDB Academy?
No prior experience is required. MongoDB Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Elections and Automatic Failover” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this MongoDB Academy lesson?
Yes. Every MongoDB Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.