{"record":{"id":"e1005fbd6e200c5f","repo":"t8y2/dbx","slug":"physical-connect","errorCode":"physical_connect","errorMessage":"physical_connect","messagePattern":"physical_connect","errorType":"error_code","errorClass":"JdbcOperationCapacityException","httpStatus":null,"severity":"error","filePath":"agents/common/src/main/java/com/dbx/agent/JdbcConnectionPoolRegistry.java","lineNumber":1594,"sourceCode":"            ConnectionFactory connectionFactory,\n            PhysicalConnectionBudget physicalConnectionBudget,\n            PhysicalConnectionCloser physicalConnectionCloser,\n            ConnectionFactoryDataSource factoryDataSource,\n            OperationDeadline deadline,\n            long closeTimeoutMillis\n        ) throws Exception {\n            CompletableFuture<Connection> outcome = new CompletableFuture<>();\n            try {\n                executor.execute(() -> completeOpen(\n                    connectionFactory,\n                    physicalConnectionBudget,\n                    physicalConnectionCloser,\n                    factoryDataSource,\n                    closeTimeoutMillis,\n                    outcome\n                ));\n            } catch (RejectedExecutionException error) {\n                throw new JdbcOperationCapacityException(\"physical_connect\", error);\n            }\n            try {\n                return outcome.get(deadline.remainingNanos(), TimeUnit.NANOSECONDS);\n            } catch (TimeoutException error) {\n                return abandon(outcome, error);\n            } catch (InterruptedException error) {\n                Thread.currentThread().interrupt();\n                return abandon(outcome, error);\n            } catch (ExecutionException error) {\n                throwOpenFailure(error.getCause());\n                throw new IllegalStateException(\"unreachable\");\n            }\n        }\n\n        private static void completeOpen(\n            ConnectionFactory connectionFactory,\n            PhysicalConnectionBudget physicalConnectionBudget,\n            PhysicalConnectionCloser physicalConnectionCloser,","sourceCodeStart":1576,"sourceCodeEnd":1612,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/common/src/main/java/com/dbx/agent/JdbcConnectionPoolRegistry.java#L1576-L1612","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Increase the physical-connect executor's queue size/thread count to match or exceed the pool's max connections","Retry the operation with backoff — it is transient capacity pressure","Ensure the pool is not being shut down while clients still request connections (coordinate lifecycle)","Rate-limit application-side connection creation bursts (warm the pool at startup)"],"exampleFix":"// before\nExecutorService exec = Executors.newFixedThreadPool(2);\n// after\nExecutorService exec = new ThreadPoolExecutor(4, 16, 60, TimeUnit.SECONDS,\n    new LinkedBlockingQueue<>(maxPoolSize), new CallerRunsPolicy());","handlingStrategy":"retry","validationCode":"if (executor.isShutdown() || executor.getQueue().remainingCapacity() == 0) {\n    // skip attempt; executor cannot accept a physical connect right now\n    throw new IllegalStateException(\"physical-connect executor saturated\");\n}","typeGuard":"static boolean isCapacityRejection(Throwable t) {\n    while (t != null) {\n        if (t instanceof JdbcOperationCapacityException) return true;\n        t = t.getCause();\n    }\n    return false;\n}","tryCatchPattern":"try {\n    conn = pool.checkout();\n} catch (Exception e) {\n    if (isCapacityRejection(e)) {\n        Thread.sleep(backoffMs); // retry with exponential backoff + jitter\n        return checkoutWithRetry(attempt + 1);\n    }\n    throw e;\n}","preventionTips":["Size the physical-connect executor queue >= pool max connections","Warm the pool at startup to avoid cold-start submission bursts","Shut down clients before/with the pool, never during live traffic","Retry transient rejections with exponential backoff and jitter"],"tags":["jdbc","backpressure","executor-saturated","rejected-execution"],"backgroundTag":"executor-capacity-exceeded","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"}