Skip to content

Election States

When building on Aeron Cluster, it helps to understand the state machine that the elections run through. This is especially useful when troubleshooting an Aeron Cluster issue as the election state for every node is available in near real-time via AeronStat.

Cluster Election State

Value Description
0 INIT. The node is preparing for a new leadership term
1 CANVASS. The node is checking connectivity between nodes, which is used to ensure a successful election is possible. This also prevents leadership bouncing between nodes with partial connectivity - see Coracle: Evaluating Consensus at the Internet Edge
2 NOMINATE. Node is nominating a leader
3 CANDIDATE_BALLOT. Node is checking if other nodes will accept it as leader
4 FOLLOWER_BALLOT. Follower has voted for a leader
5 LEADER_LOG_REPLICATION. [Leader only] Leader is waiting for followers to replicate any missing log entries
6 LEADER_REPLAY [Leader only] Leader is replaying the local log
7 LEADER_INIT [Leader only] Leader is initialising internal state for new leadership term
8 LEADER_READY [Leader only] Leader is ready, and is awaiting followers to mark themselves FOLLOWER_READY
9 FOLLOWER_LOG_REPLICATION [Follower only] Follower is replicating missing log entries from the leader
10 FOLLOWER_REPLAY [Follower only] Follower is replaying the local log in preparing for following a new leader
11 FOLLOWER_CATCHUP_INIT [Follower only] The node is preparing for receiving a replay from the leader to catch up in current term
12 FOLLOWER_CATCHUP_AWAIT [Follower only] The node is awaiting a join from the leader for catch up
13 FOLLOWER_CATCHUP [Follower only] Follower is replaying the log in order to catch up to leader's live position and be able to join the live log
14 FOLLOWER_LOG_INIT [Follower only] Follower is initializing internal state to join the live log on the leader
15 FOLLOWER_LOG_AWAIT [Follower only] Follower's clustered service is processing the log, and the consensus module is awaiting this in order to join the live log of the leader
16 FOLLOWER_READY [Follower only] Follower is ready, and published the append position to the leader to let the leader know the follower is ready for the new term
17 CLOSED The election is closed

See also:

State diagram


This is diagram is correct as of Aeron 1.37.0.

Note the 3 node roles are highlighted in the 3 sections (Follower, Candidate and Leader)

CandidateFollowerLeaderCandidateBallot3 [Candidate]Canvass1 [Follower]Nominate2 [Follower]FollowerBallot4 [Follower]FollowerLogReplication9 [Follower]FollowerReplay10 [Follower]FollowerCatchupInit11 [Follower]FollowerCatchupAwait12 [Follower]FollowerCatchup13 [Follower]FollowerLogInit14 [Follower]FollowerLogAwait15 [Follower]FollowerReady16 [Follower]LeaderLogReplication5 [Leader]LeaderReplay6 [Leader]LeaderInit7 [Leader]LeaderReady8 [Leader]Init0 [Prepare for election]Closed17 [Final Election State]>1 nodesin clusterThe log is newerthan candidateif acceptingas followerTimeoutElection timeoutand is not leaderLog to replicateNo log to replicateLogreplicatedleadership termdiffersMust catch upNothing to catch upIf 1node clusterWins vote