t8y2/dbx · error · IllegalStateException

JDBC pool registry must be attached before connecting

Error message

JDBC pool registry must be attached before connecting

What it means

attachConnectionPoolRegistry installs the JDBC connection-pool registry on the agent session, but only while the session is still pristine. If the session has already been connected (connectParams set), has a live connection, or holds a pooled lease, the registry cannot be safely attached, so the library throws this IllegalStateException.

Source

Thrown at agents/common/src/main/java/com/dbx/agent/AbstractJdbcAgent.java:284

    @Override
    public synchronized void disconnect() {
        uncheckedVoid(() -> {
            closeCurrentConnection();
            afterDisconnect();
            connectParams = null;
            poolIdentity = null;
            sessionAffinity = false;
            requestActive = false;
            leasePinnedAtRequestStart = false;
            pooledConnectionPoisoned = false;
            identifierQuote = "";
        });
    }

    final synchronized void attachConnectionPoolRegistry(JdbcConnectionPoolRegistry registry) {
        if (connectParams != null || connection != null || pooledLease != null) {
            throw new IllegalStateException("JDBC pool registry must be attached before connecting");
        }
        poolRegistry = registry;
    }

    public boolean supportsConnectionPooling() {
        return true;
    }

    final boolean isConnectionValid(Connection connection, int timeoutSecs) {
        if (connection == null) {
            return false;
        }
        try {
            if (connection.isClosed()) {
                return false;
            }
            String validationQuery = connectionValidationQuery();
            if (validationQuery == null || validationQuery.isBlank()) {

View on GitHub (pinned to c0390bff16)

Solutions

Attach the pool registry immediately after constructing the agent, before any connect/dispatch call
Create a fresh agent instance and attach the registry before connecting
Audit initialization order so pool setup precedes the first request
Check lifecycle hooks that may trigger an implicit connect before registry attachment

Example fix

// before
agent.connect(params);
agent.attachConnectionPoolRegistry(registry); // throws
// after
agent.attachConnectionPoolRegistry(registry);
agent.connect(params);

Defensive patterns

Strategy: validation

Validate before calling

if (agent.getConnection() == null && !agent.isInitialized()) {
    agent.attachConnectionPoolRegistry(registry);
}

Type guard

boolean canAttachRegistry(AbstractJdbcAgent a) {
    return !a.isSessionEstablished(); // no connectParams, connection, or pooled lease
}

Try / catch

try {
    agent.attachConnectionPoolRegistry(registry);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("must be attached before connecting")) {
        agent = agentFactory.withPoolRegistry(registry); // recreate fresh
    }
}

Prevention

Attach the registry as the first lifecycle step after agent construction
Never interleave connect() and pool wiring in arbitrary order
Use a factory/builder that guarantees registry attachment before connect
Add an initialization-order assertion in integration tests

When it happens

Trigger: Calling attachConnectionPoolRegistry after connect()/dispatchForRuntime has already run on the same agent instance, or while a pooled lease is held.

Common situations: Reconfiguring an agent mid-session; wiring the pool registry in a lifecycle callback that runs after the first query; sharing one agent instance across initialization phases with out-of-order setup.

Related errors

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