t8y2/dbx · error · IllegalStateException

Agent session already exists: {sessionId}

Error message

Agent session already exists: {sessionId}

What it means

MultiSessionJsonRpcServer.openSession throws IllegalStateException when sessions.putIfAbsent finds an existing session under the same agentSessionId. Session IDs are caller-supplied, so this enforces uniqueness: one live agent session per ID.

Source

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

                new IllegalStateException("Agent session limit reached: " + MAX_SESSIONS)
            );
        }
        Session session;
        if (sessionHandlerFactory != null) {
            session = new Session(sessionHandlerFactory.get());
        } else {
            DatabaseAgent agent = agentFactory.get();
            if (poolRegistry.isEnabled()
                && agent instanceof AbstractJdbcAgent jdbcAgent
                && jdbcAgent.supportsConnectionPooling()) {
                jdbcAgent.attachConnectionPoolRegistry(poolRegistry);
                ensureMaintenanceStarted();
            }
            session = new Session(new JsonRpcServer(agent));
        }
        Session existing = sessions.putIfAbsent(sessionId, session);
        if (existing != null) {
            throw new IllegalStateException("Agent session already exists: " + sessionId);
        }
        try {
            return session.connect(params);
        } catch (Exception error) {
            sessions.remove(sessionId, session);
            session.quarantineAndClose(cleanup);
            throw error;
        }
    }

    private Object closeSession(String sessionId) {
        Session session = sessions.remove(sessionId);
        if (session != null) {
            boolean replaceRuntime = session.quarantineAndClose(cleanup);
            if (replaceRuntime) {
                throw AgentRpcError.resource(
                    "close",
                    new IllegalStateException("JDBC quarantine operation limit reached")

View on GitHub (pinned to c0390bff16)

Solutions

1. Generate a unique agentSessionId (UUID) per session, or reuse the existing session via the request path instead of opening again
2. Close the existing session with the same ID before reopening
3. On receiving this error, treat the session as already connected and proceed with handleRequest using that ID
4. Serialize session-open logic client-side to avoid duplicate concurrent opens

Example fix

// before
server.openSession("main", connectParams);
// after
String id = UUID.randomUUID().toString();
server.openSession(id, connectParams); // unique per run

// before opening, check whether the id already exists by attempting a harmless request
boolean exists = true;
try { server.handleRequest(id, pingRequest); } catch (IllegalStateException e) { exists = false; }
if (!exists) server.openSession(id, connectParams);

try {
    server.openSession(sessionId, connectParams);
} catch (IllegalStateException e) {
    // already open: reuse it
}

When it happens

Trigger: Calling openSession twice with the same agentSessionId without closing the first; a concurrent client racing to open the same ID; reusing an ID from a previous run whose session was not closed.

Common situations: Client retry after a timeout where the first open actually succeeded; fixed/default session IDs in client config; scripts re-run without closing previous sessions.

Related errors

• Agent session not found: {sessionId}
• agentSessionId is required
• Agent session is quarantined
• agent session already exists: %s
• agent session already exists: %s

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