t8y2/dbx · error · SQLException

Failed to checkout JDBC connection

Error message

Failed to checkout JDBC connection

What it means

Generic wrapping SQLException thrown by the checkout executor when a checkout task fails with a checked exception that is neither SQLException, RuntimeException, nor Error. The original failure is preserved as the cause. It indicates an unexpected checked exception escaped the checkout path.

Source

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

                throwCheckoutFailure(error.getCause());
                throw new IllegalStateException("unreachable");
            }
        }

        private static void throwCheckoutFailure(Throwable error) throws SQLException {
            if (error instanceof AgentRpcError rpcError) {
                throw rpcError;
            }
            if (error instanceof SQLException sqlError) {
                throw sqlError;
            }
            if (error instanceof RuntimeException runtimeError) {
                throw runtimeError;
            }
            if (error instanceof Error fatal) {
                throw fatal;
            }
            throw new SQLException("Failed to checkout JDBC connection", error);
        }

        @Override
        public void close() {
            executor.shutdownNow();
        }
    }

    private static final class ConnectionReleaseExecutor implements AutoCloseable {
        private final ExecutorService executor;

        private ConnectionReleaseExecutor(int maximumConcurrentReleases) {
            executor = boundedExecutor(maximumConcurrentReleases, "dbx-jdbc-release");
        }

        private void release(
            HikariDataSource dataSource,
            Connection connection,

View on GitHub (pinned to c0390bff16)

Solutions

1. Inspect the cause chain (getCause()) to find the real checked exception
2. Fix the underlying factory/DataSource so it throws SQLException or RuntimeException per JDBC contract
3. Ensure custom connection factories catch and translate checked exceptions into SQLException
4. Log the full stack trace; if it comes from library internals, report with the cause

Example fix

// before
} catch (SQLException e) { log(e); }
// after
try {
    Lease lease = pool.checkout();
} catch (SQLException e) {
    log("checkout failed", e.getCause()); // inspect real cause
    throw e;
}

// Validate custom factories up front:
try (Connection c = testFactoryDataSource.getConnection()) { }
// any non-SQL checked exception here is the root problem

static boolean isWrappedCheckedFailure(SQLException e) {
    return "Failed to checkout JDBC connection".equals(e.getMessage()) && e.getCause() != null;
}

try {
    lease = pool.checkout();
} catch (SQLException e) {
    Throwable cause = e.getCause();
    log.error("checkout failed by {}", cause == null ? e : cause);
    throw e;
}

When it happens

Trigger: A checked exception (e.g. IOException, ClassNotFoundException, custom checked exception) thrown inside DataSource.getConnection() or a wrapper callback during checkout that the executor does not map to SQLException directly.

Common situations: Custom ConnectionFactory/DataSource implementations throwing checked non-SQL exceptions; driver initialization failures surfaced as checked exceptions; misconfigured custom wrappers in the connection factory chain.

Related errors

• JDBC Session was quarantined while waiting for a connection
• JDBC connection pool registry is closed
• No active JDBC checkout owns physical connection creation
• Not a wrapper for <iface name>
• JDBC pool registry must be attached before connecting

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