t8y2/dbx · error · JdbcOperationCapacityException

physical_connect

physical_connect

Error message

physical_connect

What it means

A JdbcOperationCapacityException with operation name 'physical_connect': thrown when the executor rejects the submitted physical-connect task because the executor's queue/threads are saturated (RejectedExecutionException). It is a capacity/backpressure signal, not a connection failure.

Source

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

            ConnectionFactory connectionFactory,
            PhysicalConnectionBudget physicalConnectionBudget,
            PhysicalConnectionCloser physicalConnectionCloser,
            ConnectionFactoryDataSource factoryDataSource,
            OperationDeadline deadline,
            long closeTimeoutMillis
        ) throws Exception {
            CompletableFuture<Connection> outcome = new CompletableFuture<>();
            try {
                executor.execute(() -> completeOpen(
                    connectionFactory,
                    physicalConnectionBudget,
                    physicalConnectionCloser,
                    factoryDataSource,
                    closeTimeoutMillis,
                    outcome
                ));
            } catch (RejectedExecutionException error) {
                throw new JdbcOperationCapacityException("physical_connect", error);
            }
            try {
                return outcome.get(deadline.remainingNanos(), TimeUnit.NANOSECONDS);
            } catch (TimeoutException error) {
                return abandon(outcome, error);
            } catch (InterruptedException error) {
                Thread.currentThread().interrupt();
                return abandon(outcome, error);
            } catch (ExecutionException error) {
                throwOpenFailure(error.getCause());
                throw new IllegalStateException("unreachable");
            }
        }

        private static void completeOpen(
            ConnectionFactory connectionFactory,
            PhysicalConnectionBudget physicalConnectionBudget,
            PhysicalConnectionCloser physicalConnectionCloser,

View on GitHub (pinned to c0390bff16)

Solutions

1. Increase the physical-connect executor's queue size/thread count to match or exceed the pool's max connections
2. Retry the operation with backoff — it is transient capacity pressure
3. Ensure the pool is not being shut down while clients still request connections (coordinate lifecycle)
4. Rate-limit application-side connection creation bursts (warm the pool at startup)

Example fix

// before
ExecutorService exec = Executors.newFixedThreadPool(2);
// after
ExecutorService exec = new ThreadPoolExecutor(4, 16, 60, TimeUnit.SECONDS,
    new LinkedBlockingQueue<>(maxPoolSize), new CallerRunsPolicy());

if (executor.isShutdown() || executor.getQueue().remainingCapacity() == 0) {
    // skip attempt; executor cannot accept a physical connect right now
    throw new IllegalStateException("physical-connect executor saturated");
}

static boolean isCapacityRejection(Throwable t) {
    while (t != null) {
        if (t instanceof JdbcOperationCapacityException) return true;
        t = t.getCause();
    }
    return false;
}

try {
    conn = pool.checkout();
} catch (Exception e) {
    if (isCapacityRejection(e)) {
        Thread.sleep(backoffMs); // retry with exponential backoff + jitter
        return checkoutWithRetry(attempt + 1);
    }
    throw e;
}

When it happens

Trigger: submit()/execute() of the physical connect task throws RejectedExecutionException because the executor is shutdown or its bounded queue is full; concurrent physical connects exceed executor capacity with an abort-saturated rejection policy.

Common situations: Burst of cold-start connection creation exceeding executor queue bounds; pool shutdown racing with in-flight connect requests; too-small executor configured for the pool's maximum pool size.

Related errors

• Agent runtime JDBC physical connection limit reached: {maxim
• JDBC pool registry must be attached before connecting
• Not connected
• JDBC Session was quarantined while waiting for a connection
• Object source is not supported

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