{"record":{"id":"f52077c2d903f54b","repo":"conductor-oss/conductor","slug":"connection-pool-failed-to-start-within-maxwaittim","errorCode":null,"errorMessage":"Connection pool failed to start within <maxWaitTime>ms","messagePattern":"Connection pool failed to start within <maxWaitTime>ms","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"ai/src/main/java/org/conductoross/conductor/ai/vectordb/postgres/PostgresVectorDB.java","lineNumber":125,"sourceCode":"    private void waitForConnectionPoolReady(DataSource dataSource) {\n        if (dataSource instanceof HikariDataSource) {\n            HikariDataSource hikariDataSource = (HikariDataSource) dataSource;\n            int maxWaitTime = 5000; // 5 seconds\n            int waitInterval = 20; // 20ms\n            int totalWaited = 0;\n\n            while (!hikariDataSource.isRunning() && totalWaited < maxWaitTime) {\n                try {\n                    Thread.sleep(waitInterval);\n                    totalWaited += waitInterval;\n                } catch (InterruptedException e) {\n                    Thread.currentThread().interrupt();\n                    throw new RuntimeException(\"Interrupted while waiting for connection pool\", e);\n                }\n            }\n\n            if (!hikariDataSource.isRunning()) {\n                throw new RuntimeException(\n                        \"Connection pool failed to start within \" + maxWaitTime + \"ms\");\n            }\n        }\n    }\n\n    @Override\n    public int updateEmbeddings(\n            String indexName,\n            String namespace,\n            String doc,\n            String parentDocId,\n            String id,\n            List<Float> embeddings,\n            Map<String, Object> metadata) {\n        if (parentDocId == null) {\n            parentDocId = id;\n        }\n        if (!pattern.matcher(namespace).matches()) {","sourceCodeStart":107,"sourceCodeEnd":143,"githubUrl":"https://github.com/conductor-oss/conductor/blob/cf7c3e4a8adfb158be778ab1ec525323c363cd3a/ai/src/main/java/org/conductoross/conductor/ai/vectordb/postgres/PostgresVectorDB.java#L107-L143","documentation":"Thrown as a plain RuntimeException by waitForConnectionPoolReady when hikariDataSource.isRunning() is still false after polling for maxWaitTime (5000ms, hardcoded). The HikariCP pool failed to start within the grace window, so operations are aborted. Note this polls isRunning() (pool started), not whether connections succeed.","triggerScenarios":"HikariDataSource configured but not starting within 5 seconds — slow DB DNS resolution, blocked initial connection attempts, misconfigured credentials causing long retries, or pool initialization hanging.","commonSituations":"Database unreachable/slow on first connect; wrong credentials causing connection retry backoff; network latency/DNS delay to the Postgres host; pool size/connection timeout misconfigured; DB refusing connections during startup.","solutions":["Verify the Postgres host is reachable and credentials are correct (jdbc:postgresql://host:5432/db, user, password).","Check network latency/DNS resolution to the database from the Conductor host.","If the DB is genuinely slow to connect, ensure the pool starts before heavy load (warmup) — note the 5000ms wait is hardcoded.","Confirm the pgvector extension and required tables exist so initial queries do not stall."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Validate reachability before relying on the pool\ntry (Connection c = dataSource.getConnection()) {\n    // DB is reachable\n} catch (SQLException e) {\n    // surface a clearer DB-connectivity error before the 5s timeout\n}","typeGuard":null,"tryCatchPattern":"// Transient pool-start slowness can warrant a retry; underlying DB outages should not loop forever.\ntry {\n    waitForConnectionPoolReady(dataSource);\n} catch (RuntimeException e) {\n    // check DB reachability/credentials, then retry once or fail with context\n}","preventionTips":["Verify DB host/credentials before deploying.","Pre-warm the Hikari pool at application startup.","Monitor DB connect latency to catch slow starts early."],"tags":["postgres","vectordb","connection-pool","database","timeout"],"backgroundTag":null,"analyzedSha":"cf7c3e4a8adfb158be778ab1ec525323c363cd3a","analyzedAt":"2026-08-14T03:33:19.897Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}