{"record":{"id":"ebf9079e419405a2","repo":"t8y2/dbx","slug":"jdbc-pool-registry-must-be-attached-before-connect","errorCode":null,"errorMessage":"JDBC pool registry must be attached before connecting","messagePattern":"JDBC pool registry must be attached before connecting","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"agents/common/src/main/java/com/dbx/agent/AbstractJdbcAgent.java","lineNumber":284,"sourceCode":"\n    @Override\n    public synchronized void disconnect() {\n        uncheckedVoid(() -> {\n            closeCurrentConnection();\n            afterDisconnect();\n            connectParams = null;\n            poolIdentity = null;\n            sessionAffinity = false;\n            requestActive = false;\n            leasePinnedAtRequestStart = false;\n            pooledConnectionPoisoned = false;\n            identifierQuote = \"\";\n        });\n    }\n\n    final synchronized void attachConnectionPoolRegistry(JdbcConnectionPoolRegistry registry) {\n        if (connectParams != null || connection != null || pooledLease != null) {\n            throw new IllegalStateException(\"JDBC pool registry must be attached before connecting\");\n        }\n        poolRegistry = registry;\n    }\n\n    public boolean supportsConnectionPooling() {\n        return true;\n    }\n\n    final boolean isConnectionValid(Connection connection, int timeoutSecs) {\n        if (connection == null) {\n            return false;\n        }\n        try {\n            if (connection.isClosed()) {\n                return false;\n            }\n            String validationQuery = connectionValidationQuery();\n            if (validationQuery == null || validationQuery.isBlank()) {","sourceCodeStart":266,"sourceCodeEnd":302,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/common/src/main/java/com/dbx/agent/AbstractJdbcAgent.java#L266-L302","documentation":"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.","triggerScenarios":"Calling attachConnectionPoolRegistry after connect()/dispatchForRuntime has already run on the same agent instance, or while a pooled lease is held.","commonSituations":"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.","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"],"exampleFix":"// before\nagent.connect(params);\nagent.attachConnectionPoolRegistry(registry); // throws\n// after\nagent.attachConnectionPoolRegistry(registry);\nagent.connect(params);","handlingStrategy":"validation","validationCode":"if (agent.getConnection() == null && !agent.isInitialized()) {\n    agent.attachConnectionPoolRegistry(registry);\n}","typeGuard":"boolean canAttachRegistry(AbstractJdbcAgent a) {\n    return !a.isSessionEstablished(); // no connectParams, connection, or pooled lease\n}","tryCatchPattern":"try {\n    agent.attachConnectionPoolRegistry(registry);\n} catch (IllegalStateException e) {\n    if (e.getMessage().contains(\"must be attached before connecting\")) {\n        agent = agentFactory.withPoolRegistry(registry); // recreate fresh\n    }\n}","preventionTips":["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"],"tags":["jdbc","lifecycle","illegal-state"],"backgroundTag":"pool-registry-attached-after-connect","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"}