t8y2/dbx · error · IllegalStateException

Agent session is quarantined

Error message

Agent session is quarantined

What it means

Session.requireActive throws IllegalStateException('Agent session is quarantined') when a request or connect is attempted on a session whose state is not ACTIVE. Sessions are quarantined after fatal failures and closed asynchronously, so operations on them are rejected to prevent use of a broken agent.

Source

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

        }

        private void expireIdleResources(long nowMillis, long idleTimeoutMillis) {
            if (state.get() != State.ACTIVE || handler != null) {
                return;
            }
            if (!lock.tryLock()) {
                return;
            }
            try {
                server.expireIdleResources(nowMillis, idleTimeoutMillis);
            } finally {
                lock.unlock();
            }
        }

        private void requireActive() {
            if (state.get() != State.ACTIVE) {
                throw new IllegalStateException("Agent session is quarantined");
            }
        }

        private enum State {
            ACTIVE,
            QUARANTINED,
            CLOSED
        }
    }
}

View on GitHub (pinned to c0390bff16)

Solutions

1. Treat this error as 'session dead': open a new session and migrate to it
2. Stop sending requests on the old session ID after any fatal error
3. Poll/wait for the old session to be removed, then open a fresh one under a new ID
4. Client-side: map IllegalStateException('quarantined') to your session-reconnect logic

Example fix

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

// track session state client-side; skip calls once a fatal error quarantined the session
if (markedDead.contains(sessionId)) {
    sessionId = server.openSession(connectParams);
}

boolean usable(Map<String,Object> s) { return "ACTIVE".equals(s.get("state")); }

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

When it happens

Trigger: Calling handleRequest or connect on a session that was quarantined (e.g. after an unrecoverable error or failed connect cleanup) but not yet removed from the sessions map; racing the quarantine/close window.

Common situations: Client keeps using a cached session after a previous call failed fatally; cleanup thread has not yet removed the quarantined session; concurrent requests hitting a session mid-quarantine.

Related errors

• JDBC pool registry must be attached before connecting
• Agent session already exists: {sessionId}
• Agent session not found: {sessionId}
• agent session not found: %s
• Not connected

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