pg (node-postgres) package not found. Install it with: npm i

Error message

pg (node-postgres) package not found. Install it with: npm install pg

What it means

Thrown by loadPg() when the dynamic import('pg') fails. The bridge deliberately treats node-postgres as an optional dependency and imports it lazily to avoid bundling issues; if the package is absent from the runtime's node_modules (or unreachable from the bundle), the import rejects and this actionable error replaces the raw module-not-found.

Source

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

      };

      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'
      );
    }
  }

  /**
   * Build pool configuration from RuVector config.
   */
  private buildPoolConfig(): PgPoolConfig {
    const poolSettings = (this.config.pool ?? {}) as Partial<PoolConfig>;

    return {
      host: this.config.host,
      port: this.config.port,
      database: this.config.database,
      user: this.config.user,
      password: this.config.password,
      ssl: this.config.ssl

View on GitHub (pinned to fa13ee4ad6)

Solutions

Install the driver in the runtime package: npm install pg (plus npm install -D @types/pg for TypeScript)
After installing, verify the runtime can resolve it: node -e "import('pg').then(() => console.log('ok'))"
For bundlers, mark pg as external so the dynamic import stays a runtime require
In pnpm monorepos, declare pg in the consuming package's dependencies, not just a sibling's

Example fix

# before
npm run start # throws: pg (node-postgres) package not found

# after
npm install pg && npm install -D @types/pg
npm run start

Defensive patterns

Strategy: validation

Validate before calling

// probe for the driver before touching the bridge
import { createRequire } from 'node:module';
const require_ = createRequire(import.meta.url);
let pgAvailable = false;
try {
  require_.resolve('pg');
  pgAvailable = true;
} catch {
  pgAvailable = false;
}
if (!pgAvailable) {
  throw new Error('pg is not installed — run: npm install pg');
}
await bridge.initialize();

Try / catch

try {
  await bridge.initialize();
} catch (err) {
  if ((err as Error).message.includes('pg (node-postgres) package not found')) {
    throw new Error('Dependency missing at runtime: npm install pg');
  }
  throw err;
}

Prevention

Declare pg (and @types/pg) as a real dependency of the deploying package, not a transitive hope
Mark pg external when bundling so the lazy import resolves at runtime
Smoke-test the production image with node -e "import('pg').then(()=>console.log('ok'))"

When it happens

Trigger: Running the bridge in a project that never installed pg; a bundler (webpack/esbuild) that resolved but then excluded the dynamic import; pnpm strict node_modules hoisting where pg is not a declared dependency of the consuming package.

Common situations: Optional peer dependency not installed after adding the integration; Docker image built from a pruned dependency tree; monorepo where pg is installed only in a sibling package.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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