{"record":{"id":"65ae16273d92c982","repo":"t8y2/dbx","slug":"jdbc-physical-operation-failed-operation","errorCode":null,"errorMessage":"JDBC physical operation failed: <operation>","messagePattern":"JDBC physical operation failed: <operation>","errorType":"exception","errorClass":"SQLException","httpStatus":null,"severity":"error","filePath":"agents/common/src/main/java/com/dbx/agent/JdbcConnectionPoolRegistry.java","lineNumber":1545,"sourceCode":"            OperationDeadline deadline = new OperationDeadline(timeoutMillis);\n            try {\n                return outcome.get(deadline.remainingNanos(), TimeUnit.NANOSECONDS);\n            } catch (TimeoutException error) {\n                SQLException failure = new PhysicalConnectionStateUnknownException(error);\n                factoryDataSource.poison(failure);\n                throw failure;\n            } catch (InterruptedException error) {\n                Thread.currentThread().interrupt();\n                SQLException failure = new PhysicalConnectionStateUnknownException(error);\n                factoryDataSource.poison(failure);\n                throw failure;\n            } catch (ExecutionException error) {\n                if (preserveCompletedFailure) {\n                    Throwable cause = error.getCause();\n                    if (cause instanceof SQLException sqlError) {\n                        throw sqlError;\n                    }\n                    throw new SQLException(\"JDBC physical operation failed: \" + operation, cause);\n                }\n                SQLException failure = new PhysicalConnectionStateUnknownException(error.getCause());\n                factoryDataSource.poison(failure);\n                throw failure;\n            }\n        }\n\n        @Override\n        public void close() {\n            executor.shutdownNow();\n        }\n    }\n\n    @FunctionalInterface\n    private interface PhysicalConnectionCall<T> {\n        T run() throws SQLException;\n    }\n","sourceCodeStart":1527,"sourceCodeEnd":1563,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/common/src/main/java/com/dbx/agent/JdbcConnectionPoolRegistry.java#L1527-L1563","documentation":"Thrown when a physical JDBC operation executed asynchronously fails: the Future.get() throws ExecutionException. If preserveCompletedFailure is set and the cause is not already a SQLException, it is wrapped as 'JDBC physical operation failed: <operation>' with the real cause attached. Otherwise the pool assumes the connection state is unknown and poisons the data source with PhysicalConnectionStateUnknownException.","triggerScenarios":"The background task performing the physical operation (connect/close/etc. named by <operation>) throws an unexpected Throwable (not SQLException) — e.g. NPE, ClassCastException, driver bug — inside the executor task.","commonSituations":"Driver bugs or incompatibilities throwing RuntimeExceptions during getConnection(); classpath conflicts after driver upgrades; OOM/stack overflow inside the physical connect; custom wrappers throwing unexpected exception types.","solutions":["Read getCause() on the SQLException to identify the underlying Throwable and fix that root failure","Verify driver version compatibility with the JVM and library after upgrades","Run the failing operation against the raw driver DataSource to reproduce outside the pool","If persistent and unexplainable, restart the pool (poisoning may have retired the data source)"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Smoke-test the raw driver outside the pool after upgrades:\ntry (Connection c = rawDriverDataSource.getConnection()) {\n    c.isValid(5);\n} // unexpected RuntimeException here predicts error 24","typeGuard":"static boolean isPhysicalOperationFailure(SQLException e) {\n    return e.getMessage() != null && e.getMessage().startsWith(\"JDBC physical operation failed:\");\n}","tryCatchPattern":"try {\n    lease = pool.checkout();\n} catch (SQLException e) {\n    if (isPhysicalOperationFailure(e)) {\n        log.error(\"physical op failed, root cause:\", e.getCause());\n        // retry with backoff only for transient-looking causes\n        throw e;\n    }\n    throw e;\n}","preventionTips":["Test driver upgrades against the pool in staging; read getCause() for the real Throwable","Watch for memory pressure/GC pauses that can destabilize async executor tasks","Keep instrumentation/agents compatible with the driver version","Retry only transient causes (network), fail fast on deterministic ones (NPE/ClassCast)"],"tags":["jdbc","async","execution-failure","driver"],"backgroundTag":"jdbc-physical-operation-failed","analyzedSha":"c0390bff16418b651f4728520d99adf8ce48829a","analyzedAt":"2026-09-05T23:05:10.900Z","contentChangedAt":"2026-09-05T23:05:10.900Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}