t8y2/dbx · error · java.lang.IllegalStateException

Agent session limit reached: <MAX_SESSIONS>

Error message

Agent session limit reached: <MAX_SESSIONS>

What it means

The multi-session agent caps concurrent sessions at MAX_SESSIONS. openSession throws IllegalStateException("Agent session limit reached: N") when opening a new sessionId while `sessions.size() >= MAX_SESSIONS` and the requested id is not already present, to bound resource usage (each session holds a MongoClient).

Source

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

                } else {
                    String sessionId = params.has("agentSessionId")
                        ? params.get("agentSessionId").getAsString()
                        : LEGACY_SESSION_ID;
                    result = session(sessionId).handle(method, params);
                }
                response.add("result", GSON.toJsonTree(result));
            } catch (Exception error) {
                JsonObject rpcError = new JsonObject();
                rpcError.addProperty("code", -1);
                rpcError.addProperty("message", error.getMessage() == null ? "Unknown error" : error.getMessage());
                response.add("error", rpcError);
            }
            return GSON.toJson(response);
        }

        private Object openSession(String sessionId, JsonObject params) {
            if (sessions.size() >= MAX_SESSIONS && !sessions.containsKey(sessionId)) {
                throw new IllegalStateException("Agent session limit reached: " + MAX_SESSIONS);
            }
            Session created = new Session(openClient(params));
            Session existing = sessions.putIfAbsent(sessionId, created);
            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);
        }

View on GitHub (pinned to c0390bff16)

Solutions

1. Close idle sessions with closeSession before opening new ones.
2. Reuse an existing sessionId instead of minting a new one per request.
3. Raise MAX_SESSIONS if the workload legitimately needs more concurrent sessions (rebuild/reconfigure the agent).
4. Add session lifecycle management (close on failure/timeout) in client code to stop leaks.

Example fix

// before (leak: never closed)
openSession("s-" + UUID.randomUUID(), params); // ... no closeSession
// after
String id = "s-" + UUID.randomUUID();
try { openSession(id, params); work(id); } finally { closeSession(id); }

// Java: bound active sessions client-side before opening
if (activeSessionCount >= MAX_SESSIONS) {
    closeOldestIdleSession(); // free a slot first
}

try { agent.openSession(sessionId, params); }
catch (IllegalStateException e) {
  if (e.getMessage().startsWith("Agent session limit reached")) {
    closeIdleSessions();
    agent.openSession(sessionId, params); // retry after freeing slots
  } else throw e;
}

When it happens

Trigger: Calling openSession with a brand-new sessionId when MAX_SESSIONS sessions are already registered; leaking sessions by never calling closeSession; repeated reconnects that open a new id each time under connection churn.

Common situations: Per-request session creation in high-traffic services; forgetting closeSession on error paths so sessions accumulate; test suites opening a session per test; scaling worker pools beyond the configured cap.

Related errors

• Agent session already exists: <sessionId>
• Agent session not found: <sessionId>
• Not connected
• agent session limit reached: {MAX_AGENT_SESSIONS}
• JDBC pool registry must be attached before connecting

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