GuidanceControlPlane not initialized. Call initialize() firs

Error message

GuidanceControlPlane not initialized. Call initialize() first.

What it means

GuidanceControlPlane.ensureInitialized() throws this from every operational method (retrieveForTask, startRun, finalizeRun/optimize) until initialize() has fully completed — the initialized flag is set only after reading guidance files, compiling the bundle, loading the retriever, and wiring gates. Constructing via createGuidanceControlPlane does NOT initialize; you must await initialize() yourself.

Source

Thrown at v3/@claude-flow/guidance/src/index.ts:729

    };
  }

  // ===== Private =====

  private async readGuidanceFile(path: string): Promise<string | null> {
    try {
      if (existsSync(path)) {
        return await readFile(path, 'utf-8');
      }
      return null;
    } catch {
      return null;
    }
  }

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

/**
 * Create a guidance control plane instance
 */
export function createGuidanceControlPlane(
  config?: Partial<GuidanceControlPlaneConfig>
): GuidanceControlPlane {
  return new GuidanceControlPlane(config);
}

/**
 * Quick setup: create and initialize the control plane
 */
export async function initializeGuidanceControlPlane(
  config?: Partial<GuidanceControlPlaneConfig>

View on GitHub (pinned to fa13ee4ad6)

Solutions

await plane.initialize() once during startup before exposing the plane to any request path
Centralize initialization in a single guarded helper (cached promise) that every entry point awaits
If initialize() rejected, fix its root cause (commonly the missing guidance file) before retrying — a failed init leaves initialized false
Pre-check plane.getBundle() !== null to confirm the compiled bundle is live before dispatching work

Example fix

// before
const plane = createGuidanceControlPlane();
plane.initialize(); // missing await
plane.startRun('task-1', 'edit'); // throws: not initialized
// after
const plane = createGuidanceControlPlane();
await plane.initialize();
plane.startRun('task-1', 'edit');

Defensive patterns

Strategy: validation

Validate before calling

let initPromise: Promise<void> | null = null;
function getPlane(plane: GuidanceControlPlane): Promise<GuidanceControlPlane> {
  initPromise ??= plane.initialize();
  return initPromise.then(() => plane);
}
// usage
const ready = await getPlane(plane); // every entry point awaits this
if (ready.getBundle() === null) throw new Error('Control plane failed to load bundle');

Type guard

function isControlPlaneReady(plane: GuidanceControlPlane): boolean {
  return plane.getBundle() !== null; // bundle is set only after initialize() completes
}

Prevention

Await initialize() once at startup and gate request handling on it
Never fire-and-forget initialize(); a rejected promise leaves initialized false
If initialize() throws, fix the cause (e.g. missing guidance file) before any other call

When it happens

Trigger: Calling plane.retrieveForTask(...) / startRun(...) immediately after construction without awaiting initialize(); omitting the await on initialize() so calls race ahead of it; an earlier initialize() that rejected (e.g. missing root guidance file) while caller code continues anyway.

Common situations: Startup races where requests arrive concurrently with initialization; refactors that move initialize() into an unawaited helper; swallowed init errors letting later calls hit the guard.

Related errors

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