t8y2/dbx · error · SQLTransientConnectionException

No active JDBC checkout owns physical connection creation

Error message

No active JDBC checkout owns physical connection creation

What it means

Thrown as SQLTransientConnectionException when computing the earliest deadline for physical connection creation finds no registered OperationDeadline. Physical connects must occur inside an active JDBC checkout that owns a deadline; this error means the code attempted to find/create a physical connection outside any such checkout scope.

Source

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

        private void poison(SQLException failure) {
            causalFailure.compareAndSet(null, failure);
            signalAttemptStateChanged();
        }

        private DeadlineRegistration registerCheckout(OperationDeadline deadline) {
            checkoutDeadlines.add(deadline);
            return new DeadlineRegistration(deadline);
        }

        private OperationDeadline currentCheckoutDeadline() throws SQLException {
            OperationDeadline earliest = null;
            for (OperationDeadline deadline : checkoutDeadlines) {
                if (earliest == null || deadline.deadlineNanos < earliest.deadlineNanos) {
                    earliest = deadline;
                }
            }
            if (earliest == null) {
                throw new SQLTransientConnectionException("No active JDBC checkout owns physical connection creation");
            }
            return earliest;
        }

        private final class DeadlineRegistration implements AutoCloseable {
            private final OperationDeadline deadline;

            private DeadlineRegistration(OperationDeadline deadline) {
                this.deadline = deadline;
            }

            @Override
            public void close() {
                checkoutDeadlines.remove(deadline);
            }
        }

        @Override

View on GitHub (pinned to c0390bff16)

Solutions

1. Ensure all physical connection acquisition goes through the pool's checkout path, which registers an OperationDeadline
2. Verify the checkout is still active (not retired/closed) when triggering physical connects
3. If invoking internal CheckoutExecutor methods directly, register a DeadlineRegistration first and close it in a finally block
4. Upgrade/report if a keepalive or validation timer triggers physical connects after checkout teardown

// Ensure physical connects happen only through pool.checkout();
// assert a checkout is active before touching the factory DataSource:
if (!pool.hasActiveCheckout()) {
    throw new IllegalStateException("physical connect requires an active checkout");
}

static boolean hasDeadlineScope(CheckoutExecutor exec) {
    return exec != null && exec.hasRegisteredDeadline();
}

try {
    lease = pool.checkout();
} catch (SQLTransientConnectionException e) {
    if (e.getMessage().contains("No active JDBC checkout")) {
        // route through pool.checkout() instead of direct factory access
    }
    throw e;
}

When it happens

Trigger: Internal code paths call earliestDeadline()/deadline computation on a CheckoutExecutor (or a physical connect is driven from the factory DataSource) without a checkout having registered a deadline via the DeadlineRegistration mechanism — e.g. using the DataSource directly outside pool.checkout().

Common situations: Calling getConnection() on the wrapped factory DataSource outside a checkout; lifecycle callbacks (e.g. connection validation/keepalive) racing with pool retirement so all registrations are already closed; misuse of internal APIs from custom code.

Related errors

• JDBC connection pool registry is closed
• JDBC pool registry must be attached before connecting
• JDBC Session was quarantined while waiting for a connection
• Not connected
• Failed to checkout JDBC connection

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