t8y2/dbx · error · PhysicalConnectionLimitException

Agent runtime JDBC physical connection limit reached: {maxim

Error message

Agent runtime JDBC physical connection limit reached: {maximum}

What it means

PhysicalConnectionLimitException thrown when the physical-connection budget semaphore cannot be acquired within the deadline: the pool already holds its maximum number of physical connections. The message interpolates the configured maximum so the operator can see the limit that was hit. This is a deliberate resource-limit signal (backpressure).

Source

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

    private static final class PhysicalConnectionBudget {
        private final int maximum;
        private final Semaphore permits;

        private PhysicalConnectionBudget(int maximum) {
            this.maximum = maximum;
            this.permits = new Semaphore(maximum, true);
        }

        private void acquire(OperationDeadline deadline) throws SQLException {
            try {
                if (permits.tryAcquire(deadline.remainingNanos(), TimeUnit.NANOSECONDS)) {
                    return;
                }
            } catch (InterruptedException error) {
                Thread.currentThread().interrupt();
                throw new SQLException("Interrupted while waiting for the JDBC physical connection budget", error);
            }
            throw new PhysicalConnectionLimitException(maximum);
        }

        private Connection wrap(
            Connection connection,
            PhysicalConnectionCloser physicalConnectionCloser,
            ConnectionFactoryDataSource factoryDataSource,
            long closeTimeoutMillis,
            ConnectionFactoryDataSource.HikariSetupAttempt setupAttempt
        ) {
            AtomicBoolean released = new AtomicBoolean();
            return (Connection) Proxy.newProxyInstance(
                JdbcConnectionPoolRegistry.class.getClassLoader(),
                new Class<?>[] {Connection.class, HikariSetupTrackedConnection.class},
                (proxy, method, arguments) -> {
                    if ("completeHikariSetup".equals(method.getName()) && method.getParameterCount() == 0) {
                        setupAttempt.completeSuccessfully();
                        return null;
                    }

View on GitHub (pinned to c0390bff16)

Solutions

Increase the configured maximum physical connection limit to match peak concurrency
Check for connection leaks — connections not returned to the pool hold permits indefinitely
Investigate slow physical connections (DB latency, network) that keep permits occupied past deadlines
Add backpressure/retry with jitter on the client side and warm the pool before traffic spikes

Example fix

// before
registry = JdbcConnectionPoolRegistry.builder().maxPhysicalConnections(5).build();
// after
registry = JdbcConnectionPoolRegistry.builder().maxPhysicalConnections(50).build();

Defensive patterns

Strategy: retry

Validate before calling

// before scaling out, confirm the limit actually matches workload:
if (expectedConcurrentPhysicalConnections >= configuredMaxPhysicalConnections) {
    raiseLimit(configuredMaxPhysicalConnections * 2);
}

Type guard

static boolean isPhysicalLimit(SQLException e) {
    Throwable t = e;
    while (t != null) {
        if (t instanceof PhysicalConnectionLimitException) return true;
        t = t.getCause();
    }
    return false;
}

Try / catch

try {
    lease = pool.checkout();
} catch (SQLException e) {
    if (isPhysicalLimit(e)) {
        Thread.sleep(backoffWithJitter());
        return checkoutWithRetry(attempt + 1);
    }
    throw e;
}

Prevention

Set max physical connections to at least peak expected concurrency
Instrument and alarm on permit wait times; rising waits predict exhaustion
Fix connection leaks — leaked connections permanently consume permits
Warm the pool before traffic spikes and keep DB/network latency low

When it happens

Trigger: Concurrent physical connects exceed the configured maximum physical connection limit and permits.tryAcquire times out at line 1685, i.e. all permits held longer than deadline.remainingNanos().

Common situations: maxPhysicalConnections configured too low for workload concurrency; slow/hung physical connections (long queries, network stalls) holding permits; leaky connections never released; cold-start storms where many requests need new physical connections at once.

Related errors

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