{"record":{"id":"1dd32e89994f1ce2","repo":"t8y2/dbx","slug":"agent-session-not-found-sessionid","errorCode":null,"errorMessage":"Agent session not found: {sessionId}","messagePattern":"Agent session not found: (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"agents/common/src/main/java/com/dbx/agent/MultiSessionJsonRpcServer.java","lineNumber":240,"sourceCode":"            return session.connect(params);\n        } finally {\n            session.close();\n        }\n    }\n\n    private Object customHandshake() {\n        SessionRpcHandler handler = sessionHandlerFactory.get();\n        try {\n            return handler.handshake();\n        } finally {\n            handler.close();\n        }\n    }\n\n    private Session session(String sessionId) {\n        Session session = sessions.get(sessionId);\n        if (session == null) {\n            throw new IllegalStateException(\"Agent session not found: \" + sessionId);\n        }\n        return session;\n    }\n\n    private void closeAllSessions() {\n        for (String sessionId : sessions.keySet()) {\n            try {\n                closeSession(sessionId);\n            } catch (AgentRpcError ignored) {\n                // Sessions are already detached; process shutdown remains the final cleanup boundary.\n            }\n        }\n    }\n\n    void runMaintenance() {\n        for (Session session : sessions.values()) {\n            try {\n                session.expireIdleResources();","sourceCodeStart":222,"sourceCodeEnd":258,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/common/src/main/java/com/dbx/agent/MultiSessionJsonRpcServer.java#L222-L258","documentation":"The private session(sessionId) helper throws IllegalStateException('Agent session not found') when the sessions map has no entry for the given ID. handleRequest uses it to route requests, so any request targeting a missing/already-closed session fails with this error.","triggerScenarios":"Sending a JSON-RPC request with an agentSessionId that was never opened, or that was closed (explicit close, quarantine cleanup after connect failure, or close-all).","commonSituations":"Client caches session IDs across agent restarts; session closed by another thread/client; ID typo or lost between calls in stateless scripts.","solutions":["Open the session first and use the returned/registered agentSessionId for subsequent requests","Detect this error client-side and re-open the session automatically before retrying","Ensure only one owner closes sessions and other clients are notified of closure","Persist/refresh the session ID rather than hardcoding an old one"],"exampleFix":"// before\nserver.handleRequest(staleSessionId, request);\n// after\ntry {\n    server.handleRequest(sessionId, request);\n} catch (IllegalStateException e) {\n    sessionId = server.openSession(connectParams);\n    server.handleRequest(sessionId, request);\n}","handlingStrategy":"try-catch","validationCode":"// keep a client-side registry of opened session ids\nif (!openedSessions.contains(sessionId)) {\n    sessionId = server.openSession(connectParams);\n    openedSessions.add(sessionId);\n}","typeGuard":"boolean sessionKnown(String id) { return id != null && openedSessions.contains(id); }","tryCatchPattern":"try {\n    return server.handleRequest(sessionId, request);\n} catch (IllegalStateException e) {\n    if (e.getMessage().contains(\"not found\")) {\n        sessionId = server.openSession(connectParams);\n        return server.handleRequest(sessionId, request);\n    }\n    throw e;\n}","preventionTips":["Refresh cached session IDs after agent restarts","Coordinate session closure among clients so IDs are not closed underneath callers","Open a session at the start of each client run rather than reusing IDs","Wrap request helpers with automatic reopen logic"],"tags":["session-management","illegal-state","jsonrpc"],"backgroundTag":"session-not-found","analyzedSha":"c0390bff16418b651f4728520d99adf8ce48829a","analyzedAt":"2026-09-05T23:05:10.900Z","contentChangedAt":"2026-09-05T23:05:10.900Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}