t8y2/dbx · error · IllegalStateException

JDBC Session was quarantined while waiting for a connection

Error message

JDBC Session was quarantined while waiting for a connection

What it means

While a request was waiting to borrow a pooled connection, the underlying session was quarantined (pooledConnectionPoisoned set, typically due to a connection failure detected elsewhere). The library evicts the borrowed connection and throws this IllegalStateException instead of returning a bad connection.

Source

Thrown at agents/common/src/main/java/com/dbx/agent/AbstractJdbcAgent.java:369

        }

        JdbcConnectionPoolRegistry.Lease borrowed;
        try {
            borrowed = borrowPooledConnection(registry, identity, params);
        } catch (Exception error) {
            synchronized (this) {
                requestActive = false;
                leasePinnedAtRequestStart = false;
            }
            throw error;
        }

        synchronized (this) {
            if (pooledConnectionPoisoned) {
                requestActive = false;
                leasePinnedAtRequestStart = false;
                borrowed.evict();
                throw new IllegalStateException("JDBC Session was quarantined while waiting for a connection");
            }
            pooledLease = borrowed;
            connection = borrowed.connection();
        }
    }

    final synchronized void finishPooledRequest(
        JdbcExecutor executor,
        boolean succeeded,
        boolean requiresSessionAffinity,
        boolean evictAfterRequest
    ) {
        if (poolRegistry == null) {
            return;
        }
        requestActive = false;
        if (pooledConnectionPoisoned) {
            releasePooledConnection(true);

View on GitHub (pinned to c0390bff16)

Solutions

Retry the request on a fresh/reconnected session
Check database availability and pool health after quarantine
Enable pool validation/keep-alive so dead connections are detected before borrow
Serialize requests or use per-request sessions to avoid mid-wait poisoning

Example fix

// before
agent.dispatchForRuntime(req); // may throw quarantine
// after
try {
    agent.dispatchForRuntime(req);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("quarantined")) {
        agent = recreateAndConnectAgent();
        agent.dispatchForRuntime(req);
    }
}

Defensive patterns

Strategy: retry

Validate before calling

if (agent.getConnection() == null) {
    agent.connect(connectParams); // ensure a healthy session before queuing requests
}

Try / catch

try {
    agent.dispatchForRuntime(req);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("quarantined")) {
        agent = recreateAgentWithPool(registry, connectParams);
        agent.dispatchForRuntime(req); // bounded retry
    }
}

Prevention

Enable pool connection validation/keep-alive to catch dead connections early
Avoid sharing one agent session across many concurrent waiters; prefer per-request sessions
Monitor pool quarantine events and alert on database outages
Bound retries with backoff after a quarantine to let the pool recover

When it happens

Trigger: Concurrent/queued requests on the same agent session when another request poisons the pooled connection; pool eviction triggered by an earlier error while this request waited in the borrow queue.

Common situations: Database outage or failover while requests are queued; stale connections reaped; another thread's query killed the session.

Related errors

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