SDKBridge not initialized. Call initialize() first.

Error message

SDKBridge not initialized. Call initialize() first.

What it means

Every SDKBridge method that depends on runtime detection funnels through ensureInitialized(); if initialize() never ran or failed, the bridge throws this guard error. this.initialized only becomes true after version detection, compatibility checks, and feature detection all succeed.

Source

Thrown at v3/@claude-flow/integration/src/sdk-bridge.ts:422

  private generateMigrationExample(oldAPI: string, newAPI: string): string {
    // Generate a simple migration example
    const oldParts = oldAPI.split('.');
    const newParts = newAPI.split('.');

    const oldCall = oldParts.length > 1
      ? `${oldParts[0]}.${oldParts[1]}(args)`
      : `${oldAPI}(args)`;

    const newCall = newParts.length > 1
      ? `new ${newParts[0]}().${newParts[1]}(args)`
      : `${newAPI}(args)`;

    return `// Before:\n${oldCall}\n\n// After:\n${newCall}`;
  }

  private ensureInitialized(): void {
    if (!this.initialized) {
      throw new Error('SDKBridge not initialized. Call initialize() first.');
    }
  }
}

/**
 * Create and initialize an SDK bridge
 */
export async function createSDKBridge(
  config?: Partial<SDKBridgeConfig>
): Promise<SDKBridge> {
  const bridge = new SDKBridge(config);
  await bridge.initialize();
  return bridge;
}

View on GitHub (pinned to fa13ee4ad6)

Solutions

await bridge.initialize() once before any API call, or use the createSDKBridge() factory which constructs and initializes in one step
If initialize() already ran and failed, fix that root error first (e.g. the version incompatibility) — this guard is only a symptom
Cache the initialized promise and await it in every entry point that touches the bridge

Example fix

// before
const bridge = new SDKBridge(config);
bridge.someApi(args); // throws: init not awaited

// after
const bridge = await createSDKBridge(config); // constructs AND initializes
bridge.someApi(args);

Defensive patterns

Strategy: validation

Validate before calling

// Single shared init gate — every call site awaits the same promise
let bridgePromise: Promise<SDKBridge> | null = null;
function getBridge(): Promise<SDKBridge> {
  bridgePromise ??= createSDKBridge(config);
  return bridgePromise;
}
// usage: const bridge = await getBridge();

Try / catch

try {
  bridge.someApi(args);
} catch (e) {
  if (e instanceof Error && e.message.includes('SDKBridge not initialized')) {
    await bridge.initialize(); // or createSDKBridge() — then retry once
    return bridge.someApi(args);
  }
  throw e;
}

Prevention

Always construct via the createSDKBridge factory
Export one initialized singleton instead of passing raw instances around
Treat initialization failure as fatal at startup — log and exit rather than limping on

When it happens

Trigger: Calling any bridged API on a new SDKBridge() instance before await bridge.initialize() completes, or after initialize() failed (e.g. on an SDK version incompatibility), leaving initialized === false.

Common situations: Forgetting to await the async initialize(); an earlier init failure being swallowed so the bridge is used uninitialized; lazily-created bridge instances racing the init promise in a callback.

Related errors

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