{"record":{"id":"712dcdd94e23f706","repo":"t8y2/dbx","slug":"failed-to-checkout-jdbc-connection","errorCode":null,"errorMessage":"Failed to checkout JDBC connection","messagePattern":"Failed to checkout JDBC connection","errorType":"exception","errorClass":"SQLException","httpStatus":null,"severity":"error","filePath":"agents/common/src/main/java/com/dbx/agent/JdbcConnectionPoolRegistry.java","lineNumber":1256,"sourceCode":"                throwCheckoutFailure(error.getCause());\n                throw new IllegalStateException(\"unreachable\");\n            }\n        }\n\n        private static void throwCheckoutFailure(Throwable error) throws SQLException {\n            if (error instanceof AgentRpcError rpcError) {\n                throw rpcError;\n            }\n            if (error instanceof SQLException sqlError) {\n                throw sqlError;\n            }\n            if (error instanceof RuntimeException runtimeError) {\n                throw runtimeError;\n            }\n            if (error instanceof Error fatal) {\n                throw fatal;\n            }\n            throw new SQLException(\"Failed to checkout JDBC connection\", error);\n        }\n\n        @Override\n        public void close() {\n            executor.shutdownNow();\n        }\n    }\n\n    private static final class ConnectionReleaseExecutor implements AutoCloseable {\n        private final ExecutorService executor;\n\n        private ConnectionReleaseExecutor(int maximumConcurrentReleases) {\n            executor = boundedExecutor(maximumConcurrentReleases, \"dbx-jdbc-release\");\n        }\n\n        private void release(\n            HikariDataSource dataSource,\n            Connection connection,","sourceCodeStart":1238,"sourceCodeEnd":1274,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/common/src/main/java/com/dbx/agent/JdbcConnectionPoolRegistry.java#L1238-L1274","documentation":"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.","triggerScenarios":"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.","commonSituations":"Custom ConnectionFactory/DataSource implementations throwing checked non-SQL exceptions; driver initialization failures surfaced as checked exceptions; misconfigured custom wrappers in the connection factory chain.","solutions":["Inspect the cause chain (getCause()) to find the real checked exception","Fix the underlying factory/DataSource so it throws SQLException or RuntimeException per JDBC contract","Ensure custom connection factories catch and translate checked exceptions into SQLException","Log the full stack trace; if it comes from library internals, report with the cause"],"exampleFix":"// before\n} catch (SQLException e) { log(e); }\n// after\ntry {\n    Lease lease = pool.checkout();\n} catch (SQLException e) {\n    log(\"checkout failed\", e.getCause()); // inspect real cause\n    throw e;\n}","handlingStrategy":"try-catch","validationCode":"// Validate custom factories up front:\ntry (Connection c = testFactoryDataSource.getConnection()) { }\n// any non-SQL checked exception here is the root problem","typeGuard":"static boolean isWrappedCheckedFailure(SQLException e) {\n    return \"Failed to checkout JDBC connection\".equals(e.getMessage()) && e.getCause() != null;\n}","tryCatchPattern":"try {\n    lease = pool.checkout();\n} catch (SQLException e) {\n    Throwable cause = e.getCause();\n    log.error(\"checkout failed by {}\", cause == null ? e : cause);\n    throw e;\n}","preventionTips":["Make custom ConnectionFactory implementations throw only SQLException/RuntimeException","Unit-test your DataSource/factory chain against the pool before production","Keep the full cause chain in logs to diagnose the original checked exception","Avoid wrapper layers that throw arbitrary checked exceptions from getConnection()"],"tags":["jdbc","connection-pool","checked-exception","wrapper"],"backgroundTag":"jdbc-checkout-failed","analyzedSha":"c0390bff16418b651f4728520d99adf8ce48829a","analyzedAt":"2026-09-05T23:05:10.900Z","contentChangedAt":"2026-09-05T23:05:10.900Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}