aeron-io/aeron · critical · ClusterException

Cluster log must be contiguous for active log event…

Error message

Cluster log must be contiguous for active log event: expectedPosition=${logPosition} joinPosition=${image.joinPosition()}

What it means

Thrown as ClusterException when the active log event for the subscribed image reports a logPosition that differs from the expected position the container recovered to. This is the counterpart of the joining-image check: even if the image joinPosition matched, the actual active log event must confirm the same expected position or the log is not contiguous.

Solutions

1. Take a new cluster snapshot so all members restore to the current log position
2. Verify cluster consensus state (leadership term, log position) is consistent across members
3. Check for clock/election misconfiguration and ensure all members run the same Aeron version
4. Restart the container so it re-runs recovery with the correct recovery plan

if (activeLog.logPosition != expectedLogPosition) {
    throw new IllegalStateException("active log event mismatch: " + activeLog.logPosition + " != " + expectedLogPosition);
}

When it happens

Trigger: A LogAdapter activeLog event arrives with activeLog.logPosition != the recovered logPosition; racing/reordered log events after election; stale active log event from a previous term delivered to the recovering container.

Common situations: Cluster member rejoined while the log advanced past its recovery point without proper catch-up; election edge cases in mixed clusters; container restored from a snapshot whose position is behind the currently active log.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Cluster log must be contiguous for joining image…
• election in progress
• invalid newLeadershipTerm - this.appendPosition=
• logSessionId was null, should always have a value
• new leader detected due to commit position - memberId=

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

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/service/ClusteredServiceAgent.java:871

            CLUSTER_ACTION_FLAGS_DEFAULT;

        final String channel = new ChannelUriStringBuilder(activeLog.channel)
            .alias(subscriptionAlias)
            .build();

        Subscription logSubscription = aeron.addSubscription(channel, activeLog.streamId);
        try
        {
            final Image image = awaitImage(activeLog.sessionId, logSubscription);
            if (image.joinPosition() != logPosition)
            {
                throw new ClusterException("Cluster log must be contiguous for joining image: " +
                    "expectedPosition=" + logPosition + " joinPosition=" + image.joinPosition());
            }

            if (activeLog.logPosition != logPosition)
            {
                throw new ClusterException("Cluster log must be contiguous for active log event: " +
                    "expectedPosition=" + logPosition + " eventPosition=" + activeLog.logPosition);
            }

            logAdapter.image(image);
            logAdapter.maxLogPosition(activeLog.maxLogPosition);
            logSubscription = null;

            final long id = ackId++;
            while (!consensusModuleProxy.ack(activeLog.logPosition, clusterTime, id, NULL_VALUE, serviceId))
            {
                idle();
            }
        }
        finally
        {
            CloseHelper.quietClose(logSubscription);
        }

View on GitHub (pinned to 6d60124e15)