{"record":{"id":"c01b1c7644c17468","repo":"aeron-io/aeron","slug":"eventcode-detail","errorCode":null,"errorMessage":"${eventCode}: ${detail}","messagePattern":"\\$\\{eventCode\\}: \\$\\{detail\\}","errorType":"exception","errorClass":"ClusterException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/ClusterBackupAgent.java","lineNumber":620,"sourceCode":"    {\n        final byte[] challengeResponse = ctx.credentialsSupplier().onChallenge(encodedChallenge);\n\n        correlationId = ctx.aeron().nextCorrelationId();\n        consensusPublisher.challengeResponse(\n            consensusPublicationGroup.current(), this.correlationId, clusterSessionId, challengeResponse);\n    }\n\n    private void onSessionEvent(\n        final long correlationId,\n        final int leaderMemberId,\n        final EventCode eventCode,\n        final String detail)\n    {\n        if (this.correlationId == correlationId)\n        {\n            if (EventCode.ERROR == eventCode || EventCode.AUTHENTICATION_REJECTED == eventCode)\n            {\n                throw new ClusterException(eventCode + \": \" + detail);\n            }\n            else if (EventCode.REDIRECT == eventCode)\n            {\n                consensusPublicationGroup.closeAndExcludeCurrent();\n                state(RESET_BACKUP, epochClock.time());\n            }\n        }\n    }\n\n    private int slowTick(final long nowMs)\n    {\n        int workCount = aeronClientInvoker.invoke();\n        if (aeron.isClosed())\n        {\n            throw new AgentTerminationException(\"unexpected Aeron close\");\n        }\n\n        if (nowMs >= markFileUpdateDeadlineMs)","sourceCodeStart":602,"sourceCodeEnd":638,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/ClusterBackupAgent.java#L602-L638","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the detail in the message to identify the cluster-side cause and fix that condition.","Check authentication/credentials configuration on both the backup context and cluster if AUTHENTICATION_REJECTED.","Verify the backup is targeting the current leader and correct cluster; restart the backup after resolving."],"exampleFix":"// before\nctx.credentialsSupplier(null); // cluster requires auth\n// after\nctx.credentialsSupplier(new MyCredentialsSupplier());","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { ClusterBackup.launch(ctx); } catch (ClusterException e) { if (e.getMessage().startsWith(\"AUTHENTICATION_REJECTED\")) { fixCredentials(); } else { log.error(\"Cluster rejected backup: {}\", e.getMessage()); } }","preventionTips":["Match credentials/authorisation config with the cluster","Target the correct cluster and leader endpoints"],"tags":["aeron","cluster","authentication"],"backgroundTag":"api-error-response","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}