ruvnet/ruflo · critical

Failed to initialize connection pool: ${(error as Error).mes

Error message

Failed to initialize connection pool: ${(error as Error).message}

What it means

Wrapper error thrown when creating the pg.Pool or the subsequent verification query fails during initialize(). The original driver message is appended, so the real cause is in the suffix: unreachable host, authentication failure, nonexistent database, SSL negotiation error, or invalid pool settings. The bridge sets isConnected = false before rethrowing.

Source

Thrown at v3/@claude-flow/plugins/src/integrations/ruvector/ruvector-bridge.ts:246

      this.lastHealthCheck = new Date();

      const connectionResult: ConnectionResult = {
        connectionId: `conn-${this.connectionId}`,
        ready: true,
        serverVersion: result.rows[0]?.version ?? 'unknown',
        ruVectorVersion: result.rows[0]?.ruvector_version ?? 'N/A',
        parameters: {
          host: this.config.host,
          port: String(this.config.port),
          database: this.config.database,
          ssl: String(!!this.config.ssl),
        },
      };

      return connectionResult;
    } catch (error) {
      this.isConnected = false;
      throw new Error(`Failed to initialize connection pool: ${(error as Error).message}`);
    }
  }

  /**
   * Load pg module dynamically.
   */
  private async loadPg(): Promise<PoolFactory> {
    try {
      // Try to import pg
      const pg: any = await import('pg');
      return pg.default ?? pg;
    } catch {
      throw new Error(
        'pg (node-postgres) package not found. Install it with: npm install pg'
      );
    }
  }

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Read the appended original message — it names the actual driver failure (ECONNREFUSED, password authentication failed, etc.)
2. Verify connectivity with the same parameters using psql 'postgres://user:pass@host:port/db?sslmode=require'
3. Fix config/env: correct host, port, database, user, password, and ssl settings; ensure they reach the process
4. For startup races, retry initialize() with backoff, and for managed DBs enable ssl or provide the CA cert

Example fix

// before
const bridge = new RuVectorBridge({ host: 'localhost', port: 5432, database: 'ruvector' });
await bridge.initialize(); // ECONNREFUSED wrapped

// after
const bridge = new RuVectorBridge({
  host: process.env.PGHOST!,
  port: Number(process.env.PGPORT ?? 5432),
  database: process.env.PGDATABASE!,
  user: process.env.PGUSER,
  password: process.env.PGPASSWORD,
  ssl: { rejectUnauthorized: false },
});
await bridge.initialize();

// preflight connectivity with the same params before pool init
import net from 'node:net';
await new Promise<void>((resolve, reject) => {
  const s = net.connect(config.port, config.host);
  s.once('connect', () => { s.destroy(); resolve(); });
  s.once('error', reject);
});
await bridge.initialize();

const maxAttempts = 5;
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
  try {
    await bridge.initialize();
    break;
  } catch (err) {
    const msg = (err as Error).message;
    if (attempt === maxAttempts || !/ECONNREFUSED|ETIMEDOUT|password authentication/.test(msg)) {
      throw new Error(`RuVector init failed: ${msg}`);
    }
    await sleep(1000 * 2 ** (attempt - 1));
  }
}

When it happens

Trigger: Wrong host/port/database/credentials in the RuVector config; Postgres behind a firewall or started after the app; ssl required by the server but disabled in config; pgvector extension present but user lacks CREATE EXTENSION rights during the verification step.

Common situations: Env vars (PGHOST/PGPASSWORD) not set in the deployed environment; docker-compose startup race where the app beats the DB; connecting to a managed Postgres that enforces TLS while config has ssl: false.

Related errors

• File not found
• Connection pool already initialized
• pg (node-postgres) package not found. Install it with: npm i
• Connection pool not initialized
• Transaction already active

AI-assisted analysis of ruvnet/ruflo@fa13ee4ad6 (2026-08-18). Data as JSON: /api/errors/1924c443bf55efd2. Report an issue: GitHub.