t8y2/dbx · warning · SQLException

Interrupted while waiting for a JDBC workload lease

Error message

Interrupted while waiting for a JDBC workload lease

What it means

Thrown when the thread waiting on a Semaphore permit for a JDBC workload lease (or pool lease) is interrupted via Thread.interrupt(). The library restores the interrupt flag and rethrows as a SQLException with the interruption as cause. It signals the caller's own cancellation, not a pool fault.

Source

Thrown at agents/common/src/main/java/com/dbx/agent/JdbcConnectionPoolRegistry.java:661

                    retireAfterCheckoutFailure(deadline);
                    throw AgentRpcError.resource("connect", causalFailure == null ? error : causalFailure);
                }
                throw error;
            }
        }

        private boolean acquirePermit(
            Semaphore permits,
            OperationDeadline deadline,
            String exhaustedMessage
        ) throws SQLException {
            try {
                if (permits.tryAcquire(deadline.remainingNanos(), TimeUnit.NANOSECONDS)) {
                    return true;
                }
            } catch (InterruptedException error) {
                Thread.currentThread().interrupt();
                throw new SQLException("Interrupted while waiting for a JDBC workload lease", error);
            }
            throw AgentRpcError.backpressure(
                "checkout",
                new SQLTransientConnectionException(exhaustedMessage)
            );
        }

        private synchronized boolean markQuarantined() {
            quarantinedLeases += 1;
            return quarantinedLeases >= maxQuarantinedOperations;
        }

        private void release(Connection connection, boolean evict, boolean workloadPermit, boolean quarantined) {
            try {
                connectionReleaseExecutor.release(
                    dataSource,
                    connection,
                    evict,

View on GitHub (pinned to c0390bff16)

Solutions

Let the application shutdown/cancellation proceed: catch SQLException, check the cause is InterruptedException, and treat it as cancelled work
Restore and honor the interrupt flag (the library already calls Thread.currentThread().interrupt()) so outer layers also cancel
Reduce checkout contention (shorter connection hold times, larger pool limits) so threads rarely block waiting for permits
If interruption is unexpected, audit which code path calls interrupt()/shutdownNow() on the worker thread

Example fix

// before
Lease lease = pool.checkout();
// after
try {
    Lease lease = pool.checkout();
} catch (SQLException e) {
    if (e.getCause() instanceof InterruptedException) {
        Thread.currentThread().interrupt(); // already set by library; treat as cancellation
        throw new CancellationException("checkout interrupted");
    }
    throw e;
}

Defensive patterns

Strategy: try-catch

Validate before calling

if (Thread.currentThread().isInterrupted()) { throw new CancellationException("already interrupted; skip checkout"); }

Type guard

static boolean isInterruption(SQLException e) {
    Throwable c = e;
    while (c != null) { if (c instanceof InterruptedException) return true; c = c.getCause(); }
    return false;
}

Try / catch

try {
    lease = pool.checkout();
} catch (SQLException e) {
    if (isInterruption(e)) {
        Thread.currentThread().interrupt();
        throw new CancellationException(e);
    }
    throw e;
}

Prevention

Do not call interrupt()/shutdownNow() on threads blocked in checkout; use pool drain/timeout APIs
Check Thread.interrupted() status before starting long checkout waits
Keep workload permits sized to actual concurrency so threads rarely block
Design shutdown to first stop submitting new checkouts, then await in-flight ones

When it happens

Trigger: A caller of pool.checkout()/lease acquisition is blocked in acquirePermit's permits.tryAcquire(deadline) because all workload/lease permits are held, and another thread interrupts the blocked thread (e.g. executor.shutdownNow(), task cancellation, shutdown hooks).

Common situations: Application shutdown while connections are saturated; cancelling a future/request whose thread is queued waiting for a lease; thread pools being torn down with shutdownNow during a burst of concurrent checkouts.

Related errors

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