aeron-io/aeron · warning · TimeoutException

timeout awaiting commit position

Error message

timeout awaiting commit position

What it means

TimeoutException (WARN) thrown in Election.followerLogReplication when a follower in the LOG_REPLICATION state fails to observe progress on the commit position within the configured election timeout (replicationDeadlineNs). The follower expected the leader to keep streaming log replication / commit-position updates but none arrived in time, so the election aborts and is retried (often via CANVASS).

Solutions

1. Verify the leader is alive and reachable; check for network partitions or firewall drops between cluster members
2. Increase ctx.electionTimeoutNs() / leaderHeartbeatTimeoutNs in the cluster config to tolerate slow replication
3. Check leader CPU/disk load; log replay and recording can starve the consensus agent thread
4. Ensure clock and scheduling: run agents on dedicated threads; check for GC pauses on the leader

Example fix

// before
ctx.electionTimeoutNs(TimeUnit.SECONDS.toNanos(1));
// after
ctx.electionTimeoutNs(TimeUnit.SECONDS.toNanos(10));

// before starting the cluster, sanity-check election timeout config
if (ctx.electionTimeoutNs() < TimeUnit.SECONDS.toNanos(5)) {
    throw new IllegalArgumentException("electionTimeoutNs too small for LOG_REPLICATION");
}

catch (TimeoutException e) {
    if (AeronException.Category.WARN == e.category()) {
        // election will re-canvas automatically; alert on repetition only
    }
}

When it happens

Trigger: Follower enters LOG_REPLICATION, but nowNs >= replicationDeadlineNs elapses without the leader's commit position advancing past replicationStopPosition.

Common situations: Leader crashed or network partition during election; slow disk/CPU on the leader delaying replication; leaderHeartbeatTimeoutNs/electionTimeoutNs set too low for large catchup volumes; leader busy recording replay.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• startupCanvassTimeoutNs=
• logSessionId was null, should always have a value
• failed to send catchup position
• failed to join catchup log as follower
• failed to join catchup log

AI-assisted analysis of aeron-io/aeron@6d60124e15 (2026-09-12). Data as JSON: /api/errors/76ed7ce8504e59e4. Report an issue: GitHub.

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/Election.java:952

                    ConsensusModuleAgent.logReplicationEnded(
                        thisMember.id(),
                        "ELECTION",
                        logReplication.srcArchiveChannel(),
                        logReplication.recordingId(),
                        leaderRecordingId,
                        logReplication.position(),
                        logReplication.hasSynced());

                    appendPosition = logReplication.position();
                    stopLogReplication();
                    updateRecordingLogForReplication(
                        replicationLeadershipTermId, replicationTermBaseLogPosition, replicationStopPosition, nowNs);
                    state(CANVASS, nowNs, "");
                    workCount++;
                }
                else if (nowNs >= replicationDeadlineNs)
                {
                    throw new TimeoutException("timeout awaiting commit position", AeronException.Category.WARN);
                }
            }
        }

        return workCount;
    }

    private int followerReplay(final long nowNs)
    {
        int workCount = 0;

        if (null == logReplay)
        {
            if (logPosition < appendPosition)
            {
                if (0 == notifiedCommitPosition)
                {
                    return publishFollowerAppendPosition(nowNs);

View on GitHub (pinned to 6d60124e15)