t8y2/dbx · error · SQLException

JDBC physical operation failed: <operation>

Error message

JDBC physical operation failed: <operation>

What it means

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.

Source

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

            OperationDeadline deadline = new OperationDeadline(timeoutMillis);
            try {
                return outcome.get(deadline.remainingNanos(), TimeUnit.NANOSECONDS);
            } catch (TimeoutException error) {
                SQLException failure = new PhysicalConnectionStateUnknownException(error);
                factoryDataSource.poison(failure);
                throw failure;
            } catch (InterruptedException error) {
                Thread.currentThread().interrupt();
                SQLException failure = new PhysicalConnectionStateUnknownException(error);
                factoryDataSource.poison(failure);
                throw failure;
            } catch (ExecutionException error) {
                if (preserveCompletedFailure) {
                    Throwable cause = error.getCause();
                    if (cause instanceof SQLException sqlError) {
                        throw sqlError;
                    }
                    throw new SQLException("JDBC physical operation failed: " + operation, cause);
                }
                SQLException failure = new PhysicalConnectionStateUnknownException(error.getCause());
                factoryDataSource.poison(failure);
                throw failure;
            }
        }

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

    @FunctionalInterface
    private interface PhysicalConnectionCall<T> {
        T run() throws SQLException;
    }

View on GitHub (pinned to c0390bff16)

Solutions

1. Read getCause() on the SQLException to identify the underlying Throwable and fix that root failure
2. Verify driver version compatibility with the JVM and library after upgrades
3. Run the failing operation against the raw driver DataSource to reproduce outside the pool
4. If persistent and unexplainable, restart the pool (poisoning may have retired the data source)

// Smoke-test the raw driver outside the pool after upgrades:
try (Connection c = rawDriverDataSource.getConnection()) {
    c.isValid(5);
} // unexpected RuntimeException here predicts error 24

static boolean isPhysicalOperationFailure(SQLException e) {
    return e.getMessage() != null && e.getMessage().startsWith("JDBC physical operation failed:");
}

try {
    lease = pool.checkout();
} catch (SQLException e) {
    if (isPhysicalOperationFailure(e)) {
        log.error("physical op failed, root cause:", e.getCause());
        // retry with backoff only for transient-looking causes
        throw e;
    }
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• JDBC pool registry must be attached before connecting
• Not connected
• JDBC Session was quarantined while waiting for a connection
• Object source is not supported
• Completion assistant search is not supported by this agent

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