conductor-oss/conductor · error · RuntimeException

Connection pool failed to start within <maxWaitTime>ms

Error message

Connection pool failed to start within <maxWaitTime>ms

What it means

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.

Source

Thrown at ai/src/main/java/org/conductoross/conductor/ai/vectordb/postgres/PostgresVectorDB.java:125

    private void waitForConnectionPoolReady(DataSource dataSource) {
        if (dataSource instanceof HikariDataSource) {
            HikariDataSource hikariDataSource = (HikariDataSource) dataSource;
            int maxWaitTime = 5000; // 5 seconds
            int waitInterval = 20; // 20ms
            int totalWaited = 0;

            while (!hikariDataSource.isRunning() && totalWaited < maxWaitTime) {
                try {
                    Thread.sleep(waitInterval);
                    totalWaited += waitInterval;
                } catch (InterruptedException e) {
                    Thread.currentThread().interrupt();
                    throw new RuntimeException("Interrupted while waiting for connection pool", e);
                }
            }

            if (!hikariDataSource.isRunning()) {
                throw new RuntimeException(
                        "Connection pool failed to start within " + maxWaitTime + "ms");
            }
        }
    }

    @Override
    public int updateEmbeddings(
            String indexName,
            String namespace,
            String doc,
            String parentDocId,
            String id,
            List<Float> embeddings,
            Map<String, Object> metadata) {
        if (parentDocId == null) {
            parentDocId = id;
        }
        if (!pattern.matcher(namespace).matches()) {

View on GitHub (pinned to cf7c3e4a8a)

Solutions

1. Verify the Postgres host is reachable and credentials are correct (jdbc:postgresql://host:5432/db, user, password).
2. Check network latency/DNS resolution to the database from the Conductor host.
3. If the DB is genuinely slow to connect, ensure the pool starts before heavy load (warmup) — note the 5000ms wait is hardcoded.
4. Confirm the pgvector extension and required tables exist so initial queries do not stall.

// Validate reachability before relying on the pool
try (Connection c = dataSource.getConnection()) {
    // DB is reachable
} catch (SQLException e) {
    // surface a clearer DB-connectivity error before the 5s timeout
}

// Transient pool-start slowness can warrant a retry; underlying DB outages should not loop forever.
try {
    waitForConnectionPoolReady(dataSource);
} catch (RuntimeException e) {
    // check DB reachability/credentials, then retry once or fail with context
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Missing connection URL - please check conductor.vectordb.pos
• Interrupted while waiting for connection pool
• Invalid namespace
• Invalid index name
• Embeddings must be of dimensions : <embeddingDimensions>

AI-assisted analysis of conductor-oss/conductor@cf7c3e4a8a (2026-08-14). Data as JSON: /api/errors/f52077c2d903f54b. Report an issue: GitHub.