{"record":{"id":"054c2aa27bd4d965","repo":"aeron-io/aeron","slug":"unknown-clustersessionid-clustersessionid","errorCode":null,"errorMessage":"unknown clusterSessionId: <clusterSessionId>","messagePattern":"unknown clusterSessionId: <clusterSessionId>","errorType":"exception","errorClass":"ClusterException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/service/ClusteredServiceAgent.java","lineNumber":330,"sourceCode":"\n    public Collection<ClientSession> clientSessions()\n    {\n        return unmodifiableClientSessions;\n    }\n\n    public void forEachClientSession(final Consumer<? super ClientSession> action)\n    {\n        sessions.forEach(action);\n    }\n\n    public boolean closeClientSession(final long clusterSessionId)\n    {\n        checkForValidInvocation();\n\n        final ContainerClientSession clientSession = sessionByIdMap.get(clusterSessionId);\n        if (clientSession == null)\n        {\n            throw new ClusterException(\"unknown clusterSessionId: \" + clusterSessionId);\n        }\n\n        if (clientSession.isClosing())\n        {\n            return true;\n        }\n\n        int attempts = 3;\n        do\n        {\n            if (consensusModuleProxy.closeSession(clusterSessionId))\n            {\n                clientSession.markClosing();\n                return true;\n            }\n            idle();\n        }\n        while (--attempts > 0);","sourceCodeStart":312,"sourceCodeEnd":348,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/service/ClusteredServiceAgent.java#L312-L348","documentation":"ClusteredServiceAgent.lookupSession (isSessionOpen-style API) looks up the given clusterSessionId in sessionByIdMap; if absent, it throws ClusterException. Services may only query client sessions the cluster currently knows about — a stale or unknown session id is a programming or lifecycle error.","triggerScenarios":"A ClusteredService calling the session-lookup API with a clusterSessionId that has never been opened, already been closed, or belongs to another cluster instance.","commonSituations":"Caching session ids across snapshots/restarts and reusing them after reconnect; responding to a client whose session was closed concurrently; deserializing a request containing a stale session id.","solutions":["Verify the session id is current: only use clusterSessionId values received in onSessionMessage/onConnect callbacks of the running instance.","Clear persisted session-id caches on service start/snapshot restore and re-learn sessions.","Handle lifecycle: treat closed sessions as gone; do not keep acting on ids after onSessionClose."],"exampleFix":"// before\nboolean open = agent.isSessionOpen(staleSessionId);\n// after\nif (knownSessionIds.contains(staleSessionId)) {\n    boolean open = agent.isSessionOpen(staleSessionId);\n} else {\n    // re-acquire session state or ignore the message\n}","handlingStrategy":"try-catch","validationCode":"// java: track ids received via service callbacks and check membership first\nif (!sessionsSeenSinceStart.contains(clusterSessionId)) {\n    // unknown to this instance; skip rather than call the agent API\n    return;\n}","typeGuard":null,"tryCatchPattern":"try {\n    isSessionOpen = ctx.isSessionOpen(clusterSessionId);\n} catch (ClusterException e) {\n    if (e.getMessage().contains(\"unknown clusterSessionId\")) {\n        // session is gone or stale; treat as closed, refresh session bookkeeping\n    } else {\n        throw e;\n    }\n}","preventionTips":["Only use clusterSessionId values delivered by the current instance's callbacks.","Invalidate cached session ids on snapshot restore and after onSessionClose.","Clear persisted session references at service start."],"tags":["java","session","lookup","not-found"],"backgroundTag":"record-not-found","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"}