aeron-io/aeron · critical · ClusterEvent

potential new election in progress

Error message

potential new election in progress

What it means

During onCanvassPosition, a member in LEADER_LOG_REPLICATION or LEADER_READY state received a canvass position with a leadershipTermId greater than its own. Since it believes it is leader of the current term, a higher term implies a new election started elsewhere — an event the leader-state machine cannot absorb, so it throws ClusterEvent to surface the conflict.

Solutions

  1. Ensure all members' mark files come from the same cluster history — restore mark files + snapshots together from one backup
  2. Restart the whole cluster from a consistent snapshot if term counters diverged
  3. Check for network partitions that let a member elect itself in a higher term
  4. Upgrade Aeron — election term-conflict handling has been hardened in later releases

Example fix

// before: node restored with mark file from the future (higher leadershipTermId)
ClusterEvent: potential new election in progress
// after: copy the authoritative mark file from the live cluster leader to the rejoining node, then restart it
Defensive patterns

Strategy: try-catch

Validate before calling

// Before rejoining a node, compare its mark file leadershipTermId with the cluster leader's
if (joiningMarkFile.leadershipTermId() > leaderMarkFile.leadershipTermId()) { /* restore correct mark file */ }

Try / catch

try {
    cluster.start();
} catch (ClusterEvent e) {
    if (e.getMessage().contains("potential new election in progress")) {
        // stop the node, align mark files with the live cluster, restart
    } else { throw e; }
}

Prevention

When it happens

Trigger: A split-brain or delayed member starts canvassing for a higher term while the current leader is actively serving (LEADER_READY/LEADER_LOG_REPLICATION); typically from clock/timeouts allowing two leaders or a stale member rejoining with a higher recorded term.

Common situations: Node rejoined after long downtime with a higher leadershipTermId in its mark file; partitioned member started its own elections; inconsistent cluster mark files after manual restore.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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

Appendix: source

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

            {
                if (Cluster.Role.LEADER == consensusModuleAgent.role())
                {
                    final long nowNs = nowNs(ctx);
                    publishNewLeadershipTerm(
                        follower,
                        logLeadershipTermId,
                        consensusModuleAgent.quorumPositionBoundedByLeaderLog(
                            appendPosition, nowNs),
                        nanosToTimestamp(ctx, nowNs));
                }
            }
            else if (logLeadershipTermId > this.leadershipTermId)
            {
                switch (state)
                {
                    case LEADER_LOG_REPLICATION:
                    case LEADER_READY:
                        throw new ClusterEvent("potential new election in progress");

                    default:
                        break;
                }
            }
        }
    }

    void onRequestVote(
        final long logLeadershipTermId,
        final long logPosition,
        final long candidateTermId,
        final int candidateId,
        final int protocolVersion)
    {
        if (INIT == state)
        {
            return;

View on GitHub (pinned to 6d60124e15)