aeron-io/aeron · error · ClusterException

${eventCode}: ${detail}

Error message

${eventCode}: ${detail}

What it means

The agent's onSessionEvent handles SessionEvent messages from the cluster for its correlationId. If the event code is ERROR or AUTHENTICATION_REJECTED the backup cannot proceed and a ClusterException wrapping the code and detail is thrown; REDIRECT is handled non-fatally by resetting the backup.

Solutions

1. Read the detail in the message to identify the cluster-side cause and fix that condition.
2. Check authentication/credentials configuration on both the backup context and cluster if AUTHENTICATION_REJECTED.
3. Verify the backup is targeting the current leader and correct cluster; restart the backup after resolving.

Example fix

// before
ctx.credentialsSupplier(null); // cluster requires auth
// after
ctx.credentialsSupplier(new MyCredentialsSupplier());

try { ClusterBackup.launch(ctx); } catch (ClusterException e) { if (e.getMessage().startsWith("AUTHENTICATION_REJECTED")) { fixCredentials(); } else { log.error("Cluster rejected backup: {}", e.getMessage()); } }

When it happens

Trigger: The cluster (or archive proxy) returns an explicit error event for the backup session's correlationId, e.g. the leader rejects the backup request or authentication of the backup session is rejected.

Common situations: Backup connecting to a cluster it is not registered/allowed to back up; authentication reject due to credentials/defaults mismatch; cluster-side errors like wrong snapshot/log state.

Related errors

• authenticator cannot be null
• not found in
• clusterMembers and endpoints differ
• response publication already added
• encoded principal max length

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

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/ClusterBackupAgent.java:620

    {
        final byte[] challengeResponse = ctx.credentialsSupplier().onChallenge(encodedChallenge);

        correlationId = ctx.aeron().nextCorrelationId();
        consensusPublisher.challengeResponse(
            consensusPublicationGroup.current(), this.correlationId, clusterSessionId, challengeResponse);
    }

    private void onSessionEvent(
        final long correlationId,
        final int leaderMemberId,
        final EventCode eventCode,
        final String detail)
    {
        if (this.correlationId == correlationId)
        {
            if (EventCode.ERROR == eventCode || EventCode.AUTHENTICATION_REJECTED == eventCode)
            {
                throw new ClusterException(eventCode + ": " + detail);
            }
            else if (EventCode.REDIRECT == eventCode)
            {
                consensusPublicationGroup.closeAndExcludeCurrent();
                state(RESET_BACKUP, epochClock.time());
            }
        }
    }

    private int slowTick(final long nowMs)
    {
        int workCount = aeronClientInvoker.invoke();
        if (aeron.isClosed())
        {
            throw new AgentTerminationException("unexpected Aeron close");
        }

        if (nowMs >= markFileUpdateDeadlineMs)

View on GitHub (pinned to 6d60124e15)