t8y2/dbx · error · IllegalStateException

Agent session not found: {sessionId}

Error message

Agent session not found: {sessionId}

What it means

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.

Source

Thrown at agents/common/src/main/java/com/dbx/agent/MultiSessionJsonRpcServer.java:240

            return session.connect(params);
        } finally {
            session.close();
        }
    }

    private Object customHandshake() {
        SessionRpcHandler handler = sessionHandlerFactory.get();
        try {
            return handler.handshake();
        } finally {
            handler.close();
        }
    }

    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()) {
            try {
                closeSession(sessionId);
            } catch (AgentRpcError ignored) {
                // Sessions are already detached; process shutdown remains the final cleanup boundary.
            }
        }
    }

    void runMaintenance() {
        for (Session session : sessions.values()) {
            try {
                session.expireIdleResources();

View on GitHub (pinned to c0390bff16)

Solutions

1. Open the session first and use the returned/registered agentSessionId for subsequent requests
2. Detect this error client-side and re-open the session automatically before retrying
3. Ensure only one owner closes sessions and other clients are notified of closure
4. Persist/refresh the session ID rather than hardcoding an old one

Example fix

// before
server.handleRequest(staleSessionId, request);
// after
try {
    server.handleRequest(sessionId, request);
} catch (IllegalStateException e) {
    sessionId = server.openSession(connectParams);
    server.handleRequest(sessionId, request);
}

// keep a client-side registry of opened session ids
if (!openedSessions.contains(sessionId)) {
    sessionId = server.openSession(connectParams);
    openedSessions.add(sessionId);
}

boolean sessionKnown(String id) { return id != null && openedSessions.contains(id); }

try {
    return server.handleRequest(sessionId, request);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("not found")) {
        sessionId = server.openSession(connectParams);
        return server.handleRequest(sessionId, request);
    }
    throw e;
}

When it happens

Trigger: 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).

Common situations: Client caches session IDs across agent restarts; session closed by another thread/client; ID typo or lost between calls in stateless scripts.

Related errors

• Agent session already exists: {sessionId}
• agentSessionId is required
• Agent session is quarantined
• JDBC pool registry must be attached before connecting
• Not connected

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