Wait, What?
Five computers can disagree about what is happening and still behave like one reliable machine—provided they agree on the same ordered history.
Raft is a consensus algorithm for replicated state machines. It lets a group of servers agree on a sequence of commands despite crashes, delayed messages, duplicated messages, partitions and leadership changes, as long as a majority remains available for progress.
For a beginner, Raft is a story about followers, candidates and one leader. For an intermediate learner, it becomes a log-replication algorithm. At advanced level, the important ideas are terms, voting restrictions, log matching and commitment rules. At professional level, Raft is also about persistence ordering, snapshots, membership changes, linearizable reads, deterministic testing and the sharp boundary between the consensus core and the storage, networking and application layers around it.
Quick Answer
Learn Raft in this order: replicated state machine → follower/candidate/leader roles → terms → election timeout → RequestVote → leader heartbeats → AppendEntries → log matching → majority replication → commit rules → crash recovery → snapshots → membership changes → client semantics → fault injection and production validation. Do not begin by memorising RPC fields. First understand the job: every healthy replica must eventually apply the same commands in the same order.
1. Begin with one state machine
Imagine a key-value store receiving:
set x = 3
set y = 8
delete xIf one server executes those commands, the result is straightforward. But if several servers must survive machine failures, they need copies of the state.
Simply copying the final state is not enough. The replicas must agree on the ordered commands that created it. Raft therefore maintains a replicated log. Each server applies committed log entries to its local state machine in order.
2. Consensus is agreement under failure
A useful first model is a cluster of five servers. A majority is three. The cluster can continue making progress with any three cooperating servers, so two servers can be unavailable without destroying availability. If too many servers disappear, progress stops rather than allowing conflicting committed histories.
This distinction is foundational: safety means the system does not decide incompatible histories; liveness means it can continue making progress. A partition can reduce liveness without requiring the algorithm to sacrifice safety.
3. Raft gives every server one of three roles
- Follower: normally waits for messages from a leader or candidate.
- Candidate: asks for votes after an election timeout.
- Leader: accepts new log proposals and coordinates replication.
This decomposition is one reason Raft was designed to be understandable. Instead of every node behaving symmetrically at all times, normal operation has a clear leader.
4. Terms divide time into logical leadership epochs
Raft numbers terms with increasing integers. Each election begins a new term. A term has at most one elected leader.
Terms act like logical epochs. If a server receives a message carrying a higher term, it learns that its knowledge is stale and updates its term, stepping down to follower when required.
This is not wall-clock time. Terms order leadership generations.
5. Elections begin after silence
A follower expects periodic communication from a valid leader. If that communication does not arrive before its election timeout, it can become a candidate, increment its term, vote for itself and request votes from the other servers.
Election timeouts are randomized so that all followers are less likely to become candidates at exactly the same moment. Randomness does not make split votes impossible; it makes repeated synchronized elections less likely.
6. A candidate needs a majority
A candidate becomes leader only after receiving votes from a majority of the cluster for its term. A server grants at most one vote per term.
But Raft does not let any candidate with a pulse win. The voter also checks that the candidate’s log is at least as up to date as its own according to Raft’s term/index comparison rule. This voting restriction is crucial to preserving committed information across leadership changes.
7. The leader sends AppendEntries
AppendEntries has two jobs. It carries new log entries, and empty calls also act as heartbeats that assert continued leadership.
A simplified leader flow is:
receive client command
append entry to local log
send AppendEntries to followers
wait for replication evidence
advance commit index when Raft's rule permits
apply committed entries to state machine
inform followers of updated commit progressThe real protocol contains term and previous-log checks because merely appending bytes is not enough; followers must agree on the history immediately before the new entries too.
8. The log-matching idea
An AppendEntries request identifies the index and term of the entry immediately preceding the new entries. A follower accepts the continuation only if its own log matches that history at the specified point.
If the histories disagree, the leader backs up the follower’s replication position and retries until it finds a shared prefix. Conflicting uncommitted suffixes can then be replaced by the leader’s history.
This is the deeper invariant: if two logs contain an entry with the same index and term, their prefixes through that entry agree under Raft’s log-matching properties.
9. Replicated is not automatically committed
An entry appearing on several machines is not enough by itself to say the command is irrevocably committed. The leader advances the commit point according to Raft’s safety rule.
One subtle but important rule is that a leader uses majority counting to directly commit entries from its current term. Earlier-term entries can become committed indirectly when a later current-term entry is committed. This restriction prevents an old entry from being declared committed using evidence that is unsafe across certain leadership histories.
This is a professional-level detail worth learning carefully because simplified explanations often erase it.
10. Why majority quorums matter
Any two majorities of the same fixed cluster overlap. That overlap gives Raft a route for important history to survive from one leadership generation to another.
For five nodes, every majority has at least three members. Two different sets of three cannot be disjoint. Quorum intersection is one of the mathematical facts beneath the algorithm’s safety story.
11. A stale leader cannot stay authoritative forever
Suppose a network partition isolates the old leader. It may continue believing it is leader locally, but it cannot commit new entries without enough replicas. Meanwhile, the majority side may elect a new leader in a higher term.
When the old leader later receives a valid higher-term message, its term is obsolete and it steps down.
The lesson is useful beyond Raft: leadership is not a permanent identity. It is authority scoped to an epoch and backed by quorum evidence.
12. Raft is crash-fault tolerant, not Byzantine consensus
Standard Raft assumes nodes may crash, restart, lose messages or be partitioned, but it does not protect against arbitrary malicious behaviour from replicas that deliberately send contradictory protocol messages.
Do not describe Raft as Byzantine fault tolerant. Different threat models require different consensus protocols and cryptographic or quorum assumptions.
13. Persistent state is part of correctness
Some Raft state must survive crashes. The original paper identifies persistent information such as the current term, the vote recorded for that term and the log.
A server cannot safely acknowledge protocol actions and then forget the state that justified them after reboot. Production implementations therefore care about the ordering between state-machine decisions, durable storage and outbound messages.
This is where “the algorithm” meets systems engineering.
14. Snapshots stop the log growing forever
Replicated logs accumulate history. Once older committed commands have been incorporated into the state machine, snapshots can compact that prefix.
A lagging follower may need a snapshot if it is too far behind for the leader to replay retained log entries. Snapshot installation therefore becomes part of recovery, not just a disk-space optimisation.
15. Membership changes are consensus too
Adding and removing servers changes what counts as a quorum. That cannot safely be treated like editing a configuration file independently on each machine.
The Raft paper describes joint consensus for configuration changes, while widely used implementations may use carefully defined variants. The important principle is that old and new quorum rules must overlap safely during the transition.
Production libraries should be followed according to their documented membership-change protocol rather than mixing algorithms from different Raft variants.
16. Consensus does not automatically solve every client-semantic problem
Raft orders commands, but applications still need policies for retries, duplicate client requests, session identity, read semantics and response recovery.
For example, a client may time out after its command was actually committed and resend it. If the operation is not naturally idempotent, the application layer may need request identifiers and deduplication.
Similarly, linearizable reads require a protocol that demonstrates the responding node is sufficiently current. Mature Raft libraries provide mechanisms for this, but “we use Raft” is not by itself a complete read-consistency specification.
17. The production implementation can separate the deterministic core from I/O
The current etcd-io/raft library is a useful example. Its README describes a minimal core Raft state machine while leaving network transport and disk I/O to the embedding system. The same state plus the same input should produce the same core output.
This separation makes fault testing much easier: messages can be delayed, reordered, dropped or replayed under a controlled harness without requiring real machines or real clocks for every protocol test.
It also makes ownership explicit. The Raft core cannot compensate for an embedding application that persists state in the wrong order or loses required messages.
18. Learn Raft by tracing three nodes before implementing five
Use nodes A, B and C and record:
event | A(term, role) | B(term, role) | C(term, role) | logs | commit indexStart all three as followers. Trigger an election on A. Predict the votes. Elect A. Append one command. Then drop one follower’s messages and predict what can still commit.
Only after the state transitions are visible should the learner write the protocol logic.
19. A five-node partition exercise
Split a five-node cluster into groups of two and three. Ask:
- Which side can elect a leader?
- Which side can commit a new entry?
- What can the minority leader believe locally?
- What happens when the partition heals?
This makes quorum reasoning concrete. Learners should explain why the minority side may retain uncommitted work yet cannot force that work into the committed history.
20. Programming education: predict before you build
Raft overloads a novice if networking, concurrency, persistence and consensus rules all arrive at once. A stronger progression is:
- Predict: what role and term should each node have after an event?
- Run: use a small deterministic simulator.
- Investigate: inspect why a vote or AppendEntries request was accepted or rejected.
- Modify: introduce one dropped message or crash.
- Make: implement one protocol component after the invariants are understood.
This aligns with programming-education research on PRIMM, code tracing and worked examples: comprehension and state reasoning should precede unsupported construction.
21. Build a deterministic test harness
Do not validate consensus only by running three processes and hoping failures occur at interesting times. Model messages as explicit events.
Your harness should be able to:
- drop a message;
- duplicate it;
- delay it;
- deliver messages in a different order;
- partition selected links;
- crash and restart nodes;
- control election ticks;
- inspect persistent and volatile state.
Deterministic schedules turn a difficult distributed failure into a reproducible test case.
22. Safety properties deserve assertions
Examples of properties to monitor in tests include:
- at most one leader per term;
- committed entries are never replaced;
- servers do not apply different commands at the same committed log index;
- applied indices do not move backwards;
- term numbers never decrease;
- a node does not grant multiple votes in one term.
A production test suite should check invariants, not merely expected happy-path outputs.
23. Timing assumptions belong mostly to liveness
Raft’s safety should not depend on messages arriving within a precise everyday latency bound. Timing choices influence how quickly leaders are elected and how stable leadership is under a real network.
Election and heartbeat settings therefore require workload measurements. Values that work inside one data centre may behave badly across high-latency or highly variable networks.
Avoid copying timeout numbers from another deployment without understanding its latency distribution and failure expectations.
24. Backpressure matters
A slow follower, large proposal stream or long network disruption can create queues and log growth. Mature implementations include flow-control and batching strategies because protocol correctness alone does not guarantee bounded resource use.
Professional distributed systems must remain safe and operationally survivable under backlog.
25. Common failure states
- Treating a heartbeat as proof that a leader can still reach a majority.
- Letting a candidate with a stale log win votes.
- Declaring every majority-replicated older-term entry directly committed without the current-term rule.
- Sending messages before required persistent state has been durably recorded.
- Applying uncommitted entries to the external state machine.
- Changing cluster membership as ordinary local configuration.
- Assuming consensus automatically deduplicates client retries.
- Using wall-clock timestamps as a substitute for Raft terms.
- Testing only stable networks.
- Calling Raft Byzantine fault tolerant.
26. Beginner-to-professional learning ladder
- Beginner: explain follower, candidate, leader and majority using three nodes.
- Foundation: trace terms, elections and heartbeats through a message table.
- Intermediate: implement RequestVote and AppendEntries logic in a deterministic simulator.
- Advanced: prove log and election invariants across crashes, partitions and stale leaders.
- Professional: add persistence, snapshots, safe membership changes, linearizable read strategy, backpressure, fault injection, invariant checking and operational metrics around a tested Raft library or implementation.
27. When Raft is not the whole answer
Raft is appropriate when a small group of crash-fault-tolerant replicas must agree on an ordered log. It is not automatically the right primitive for massive fan-out, Byzantine environments, disconnected-first collaboration, eventually consistent workloads or every form of distributed storage.
The professional skill is not “use consensus everywhere.” It is recognising which shared decisions actually require consensus.
28. Ownership boundary
This article owns the specific Raft learning job: terms, elections, leader authority, log replication, commitment, crash recovery, snapshots, membership changes and production validation. It is a focused child of the broader distributed-algorithms material. It does not replace general consensus theory, Byzantine protocols, distributed databases, network security, operating-system design, MindOS, Bolt, Student/Studying Interface or any private eduKateAI implementation.
Sources and further reading
- Diego Ongaro and John Ousterhout, “In Search of an Understandable Consensus Algorithm,” USENIX ATC 2014: USENIX.
- The Raft consensus project, including the extended paper, visualisations and teaching resources: raft.github.io.
etcd-io/raft, current production-oriented Raft library and implementation notes: GitHub.- ACM/IEEE-CS/AAAI CS2023, systems and algorithmic foundations: CS2023.
- Sue Sentance, Jane Waite and Maria Kallia, PRIMM programming-education research: SIGCSE 2019.
- Matthew Hassan et al., research on code tracing as a foundational programming skill: SIGCSE 2022.
Professional rule: you understand Raft when you can explain not only how a leader is elected, but why an old leader cannot safely rewrite committed history, which state must survive a crash, and exactly what guarantees still depend on the storage, network and client layers outside the consensus core.
