{"record":{"id":"4904a98848ee0cd9","repo":"aeron-io/aeron","slug":"clashing-open-clustersessionid-clustersessionid","errorCode":null,"errorMessage":"clashing open clusterSessionId=<clusterSessionId> leadershipTermId=<leadershipTermId> logPosition=<logPosition>","messagePattern":"clashing open clusterSessionId=<clusterSessionId> leadershipTermId=<leadershipTermId> logPosition=<logPosition>","errorType":"exception","errorClass":"ClusterException","httpStatus":null,"severity":"critical","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/service/ClusteredServiceAgent.java","lineNumber":521,"sourceCode":"        clusterTime = timestamp;\n        service.onTimerEvent(correlationId, timestamp);\n    }\n\n    void onSessionOpen(\n        final long leadershipTermId,\n        final long logPosition,\n        final long clusterSessionId,\n        final long timestamp,\n        final int responseStreamId,\n        final String responseChannel,\n        final byte[] encodedPrincipal)\n    {\n        this.logPosition = logPosition;\n        clusterTime = timestamp;\n\n        if (sessionByIdMap.containsKey(clusterSessionId))\n        {\n            throw new ClusterException(\"clashing open clusterSessionId=\" + clusterSessionId +\n                \" leadershipTermId=\" + leadershipTermId + \" logPosition=\" + logPosition);\n        }\n\n        final ContainerClientSession session = new ContainerClientSession(\n            clusterSessionId, responseStreamId, responseChannel, encodedPrincipal, this);\n\n        if (Role.LEADER == role && ctx.isRespondingService())\n        {\n            session.connect(aeron);\n        }\n\n        addSession(session);\n        service.onSessionOpen(session, timestamp);\n    }\n\n    void onSessionClose(\n        final long leadershipTermId,\n        final long logPosition,","sourceCodeStart":503,"sourceCodeEnd":539,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/service/ClusteredServiceAgent.java#L503-L539","documentation":"When the log notifies the service agent of a session open (onSessionOpen path), the agent checks sessionByIdMap for an existing session with the same clusterSessionId. A duplicate indicates corrupted or replayed log state and throws ClusterException, since two live sessions cannot share one id.","triggerScenarios":"Processing a session-open log event for a clusterSessionId already present in sessionByIdMap — e.g. replaying a log position already applied, a duplicated log event, or internal bookkeeping failure between snapshot and replay.","commonSituations":"Restoring from an inconsistent snapshot while replaying a log; running a service against the wrong/overlapping log; a bug in log recovery causing double application of the same open event.","solutions":["Verify the snapshot/log pairing: ensure the snapshot was taken at or before the log position being replayed, with no overlap.","Point the service at the correct cluster directory/log; a mismatched or foreign log can contain ids already in memory.","If state files are corrupted, restore from a known-good snapshot and log; report persistent duplication as a bug to the Aeron project."],"exampleFix":"// before\n# start service with snapshot S and log L where L overlaps S\n// after\n# ensure log position >= snapshot position\nctx.clusterDir(correctDir); // snapshot + log from the same cluster instance","handlingStrategy":"validation","validationCode":"// java: confirm snapshot/log consistency before starting the service\nlong snapshotPos = readSnapshotLogPosition(snapshotFile);\nlong replayFrom = readRecoveryPlanLogPosition();\nif (replayFrom < snapshotPos) {\n    throw new IllegalStateException(\"log position overlaps snapshot; inconsistent recovery plan\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    serviceContainer.start();\n} catch (ClusterException e) {\n    if (e.getMessage().contains(\"clashing open clusterSessionId\")) {\n        // stop, restore a consistent snapshot+log pair, then restart\n    }\n    throw e;\n}","preventionTips":["Always restore snapshots and logs from the same cluster instance and recovery plan.","Take snapshots only at committed positions and never mix backup files from different clusters.","Monitor for duplicated session-open events after crash recovery."],"tags":["java","session","log-replay","state"],"backgroundTag":"invalid-state-transition","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}