t8y2/dbx · error · java.lang.IllegalStateException

Agent session not found: <sessionId>

Error message

Agent session not found: <sessionId>

What it means

The Session helper's session(sessionId) lookup returns the registered Session or throws IllegalStateException("Agent session not found: <sessionId>") when the id is absent from the sessions map. Any per-session operation routed under an unknown/closed id fails fast rather than with a NullPointerException.

Source

Thrown at agents/drivers/mongodb/src/main/java/com/dbx/agent/mongodb/MongoAgent.java:2036

            if (existing != null) {
                created.close();
                throw new IllegalStateException("Agent session already exists: " + sessionId);
            }
            return Collections.singletonMap("ok", true);
        }

        private Object closeSession(String sessionId) {
            Session removed = sessions.remove(sessionId);
            if (removed != null) {
                removed.close();
            }
            return Collections.singletonMap("ok", true);
        }

        private Session session(String sessionId) {
            Session session = sessions.get(sessionId);
            if (session == null) {
                throw new IllegalStateException("Agent session not found: " + sessionId);
            }
            return session;
        }

        private void closeAllSessions() {
            for (String sessionId : sessions.keySet()) {
                closeSession(sessionId);
            }
        }

        private static String requiredSessionId(JsonObject params) {
            if (!params.has("agentSessionId") || params.get("agentSessionId").getAsString().trim().isEmpty()) {
                throw new IllegalArgumentException("agentSessionId is required");
            }
            return params.get("agentSessionId").getAsString();
        }

        private void writeResponse(String response) {

View on GitHub (pinned to c0390bff16)

Solutions

  1. Re-open the session with openSession before retrying the operation.
  2. Verify the sessionId string matches the one used at openSession exactly.
  3. Handle close events: invalidate cached session ids after closeSession/shutdown.
  4. Add a health/get-style check to confirm a session exists before issuing data operations.

Example fix

// before
find("worker-1", params); // session closed earlier
// after
try { find("worker-1", params); }
catch (IllegalStateException e) {
  if (e.getMessage().contains("session not found")) { openSession("worker-1", openParams); find("worker-1", params); }
  else throw e;
}
Defensive patterns

Strategy: try-catch

Validate before calling

// Java: verify the session exists before use
if (!knownOpenSessions.contains(sessionId)) {
    agent.openSession(sessionId, openParams);
}

Try / catch

try { result = agent.dispatch(sessionOp); }
catch (IllegalStateException e) {
  if (e.getMessage().startsWith("Agent session not found")) {
    agent.openSession(sessionId, openParams); // reopen and retry
    result = agent.dispatch(sessionOp);
  } else throw e;
}

Prevention

When it happens

Trigger: Calling a session-scoped method with a sessionId that was never opened, or one already closed via closeSession/closeAllSessions; agent restart clearing the map while the client still references old ids; typo'd or case-mismatched session id.

Common situations: Stale session handles after agent process restart; closeSession racing subsequent requests; workers configured with different session ids than the opener; connection drops triggering closeAllSessions.

Related errors

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/1d88f5fd4c616e08. Report an issue: GitHub.