ruvnet/ruflo · error · Error

ruvLLM bridge not initialized. Call with config first.

Error message

ruvLLM bridge not initialized. Call with config first.

What it means

Thrown by getRuvllmBridge when the singleton instance is null and no config argument was supplied. The singleton is created lazily on the first call (which must pass config); subsequent calls return the instance without config. Calling getRuvllmBridge() with no config before any config-bearing call has bootstrapped it triggers this.

Source

Thrown at v3/@claude-flow/cli/src/appliance/ruvllm-bridge.ts:335

    if (/^(convert|change)\s+(var|let)\s+to\s+const$/i.test(t)) {
      return 'Use the Edit tool to replace `var`/`let` declarations with `const`.';
    }
    if (/^remove\s+console\.(log|warn|error|debug|info)$/i.test(t)) {
      const m = t.toLowerCase().match(/console\.(\w+)/)?.[1] ?? 'log';
      return `Use the Edit tool to remove all \`console.${m}\` calls.`;
    }
    return null;
  }
}

// ── Singleton accessor ──────────────────────────────────────

let instance: RuvllmBridge | null = null;

/** Get or create the singleton RuvllmBridge. Config required on first call. */
export function getRuvllmBridge(config?: RuvllmConfig): RuvllmBridge {
  if (!instance && config) instance = new RuvllmBridge(config);
  if (!instance) throw new Error('ruvLLM bridge not initialized. Call with config first.');
  return instance;
}

/** Reset the singleton (useful for tests). */
export function resetRuvllmBridge(): void { instance = null; }

/** Check whether @ruvector/core is importable without loading the bridge. */
export async function isRuvllmAvailable(): Promise<boolean> {
  try { await import('@ruvector/core'); return true; } catch { return false; }
}

View on GitHub (pinned to 6b01dc5a68)

Solutions

Ensure getRuvllmBridge(config) runs once at startup, before any getRuvllmBridge() calls — move bootstrap to the application entrypoint.
After resetRuvllmBridge() in tests, immediately re-initialize with getRuvllmBridge(testConfig).
Have consumers accept the bridge via dependency injection rather than calling the singleton accessor directly, so init order is explicit.
If accessors may run pre-bootstrap, guard with isRuvllmAvailable() or a flag and initialize lazily at that point.

Example fix

// before
// somewhere in a route handler:
const bridge = getRuvllmBridge(); // throws if not yet bootstrapped

// after
// in app entrypoint:
getRuvllmBridge({ modelsDir: process.env.RUV_MODELS_DIR! });
// then anywhere:
const bridge = getRuvllmBridge();

Defensive patterns

Strategy: validation

Validate before calling

// Bootstrap once at app entrypoint before any no-arg accessor:
getRuvllmBridge({ modelsDir: process.env.RUV_MODELS_DIR! });
// subsequent calls are safe:
const bridge = getRuvllmBridge();

Type guard

function isBridgeInitialized(b: RuvllmBridge | null): b is RuvllmBridge {
  return b !== null;
}

Try / catch

try {
  return getRuvllmBridge();
} catch (e) {
  if (e instanceof Error && /not initialized/.test(e.message)) {
    throw new Error('call getRuvllmBridge(config) at startup first');
  }
  throw e;
}

Prevention

Bootstrap the singleton at the application entrypoint.
Inject the bridge via DI instead of scattered singleton accessors.
Re-initialize immediately after resetRuvllmBridge() in tests.
Guard consumers with an availability check before access.

When it happens

Trigger: A module calls getRuvllmBridge() (no args) during startup before the bootstrap code has run getRuvllmBridge(config). Also fires after resetRuvllmBridge() if a no-arg accessor runs before re-initialization, or when the bootstrapping call itself was skipped due to a config-load failure.

Common situations: Import-order problems where a consumer module is evaluated before the bootstrap module; conditional bootstrap (only runs in certain modes) leaving the singleton null in others; tests that resetRuvllmBridge() and forget to re-initialize before the next accessor call.

Related errors

AI-assisted analysis of ruvnet/ruflo@6b01dc5a68 (2026-08-12). Data as JSON: /api/errors/dbbf36ae36399cfb. Report an issue: GitHub.