RuVector Bridge not initialized. Call initialize() first.

Error message

RuVector Bridge not initialized. Call initialize() first.

What it means

Thrown by RuVectorBridge.ensureInitialized() when this.vectorOps or this.connectionManager is unset, i.e. the bridge's initialize() never completed successfully. Every public operation routes through this guard, so any vector/search call made before (or after a failed) initialize() fails fast instead of dereferencing undefined internals.

Source

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

      memoryStats: {
        usedBytes: 0, // Would need OS-level access
        peakBytes: 0,
        indexBytes: Number(stats.total_size),
        cacheBytes: 0,
      },
    };
  }

  // ===========================================================================
  // Private Helper Methods
  // ===========================================================================

  /**
   * Ensure the plugin is initialized.
   */
  private ensureInitialized(): void {
    if (!this.vectorOps || !this.connectionManager) {
      throw new Error('RuVector Bridge not initialized. Call initialize() first.');
    }
  }

  /**
   * Ensure pgvector extension is installed.
   */
  private async ensureExtension(): Promise<void> {
    try {
      await this.connectionManager!.query("CREATE EXTENSION IF NOT EXISTS vector");
      this.logger.debug('pgvector extension ensured');
    } catch (error) {
      this.logger.warn('Could not create pgvector extension (may require superuser privileges)', error);
    }
  }

  /**
   * Forward connection manager events to plugin event bus.
   */

View on GitHub (pinned to fa13ee4ad6)

Solutions

Await bridge.initialize() in bootstrap and only register routes/workers afterward
If initialize() failed, exit or re-run it; do not let the app continue in a half-initialized state
Expose readiness from the bridge and gate request handling on it (fail health checks until ready)

Example fix

// before
const bridge = new RuVectorBridge(config);
await bridge.similaritySearch(queryVec, 10); // throws

// after
const bridge = new RuVectorBridge(config);
await bridge.initialize();
await bridge.similaritySearch(queryVec, 10);

Defensive patterns

Strategy: validation

Validate before calling

if (!isConnected(bridge)) {
  await bridge.initialize();
}
await bridge.similaritySearch(queryVector, 10);

Type guard

const isBridgeInitialized = (b: { isConnected?: boolean }): boolean =>
  b.isConnected === true;

Try / catch

try {
  await bridge.upsert(vectors);
} catch (err) {
  if (err instanceof Error && err.message.includes('Call initialize() first')) {
    await bridge.initialize();
    await bridge.upsert(vectors); // retry once after init
  } else {
    throw err;
  }
}

Prevention

Await bridge.initialize() in bootstrap and register routes/workers only afterwards
Wire the bridge's ready state into health/readiness probes
Never swallow initialize() failures — half-initialized bridges surface as this error on every call

When it happens

Trigger: Calling any bridge operation (upsert, search, delete, index ops) on a freshly constructed RuVectorBridge; using the bridge after initialize() threw — e.g. the DB was down at boot and the error was swallowed by a catch that continued serving.

Common situations: Missing await on initialize() in startup; fire-and-forget init inside an event handler; health-check traffic arriving before async bootstrap finishes; initialize() failed on transient DB unavailability and the process kept running.

Related errors

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