{"record":{"id":"f92bb53850975e66","repo":"ruvnet/ruflo","slug":"guidancecontrolplane-not-initialized-call-initial","errorCode":null,"errorMessage":"GuidanceControlPlane not initialized. Call initialize() first.","messagePattern":"GuidanceControlPlane not initialized\\. Call initialize\\(\\) first\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/guidance/src/index.ts","lineNumber":729,"sourceCode":"    };\n  }\n\n  // ===== Private =====\n\n  private async readGuidanceFile(path: string): Promise<string | null> {\n    try {\n      if (existsSync(path)) {\n        return await readFile(path, 'utf-8');\n      }\n      return null;\n    } catch {\n      return null;\n    }\n  }\n\n  private ensureInitialized(): void {\n    if (!this.initialized) {\n      throw new Error('GuidanceControlPlane not initialized. Call initialize() first.');\n    }\n  }\n}\n\n/**\n * Create a guidance control plane instance\n */\nexport function createGuidanceControlPlane(\n  config?: Partial<GuidanceControlPlaneConfig>\n): GuidanceControlPlane {\n  return new GuidanceControlPlane(config);\n}\n\n/**\n * Quick setup: create and initialize the control plane\n */\nexport async function initializeGuidanceControlPlane(\n  config?: Partial<GuidanceControlPlaneConfig>","sourceCodeStart":711,"sourceCodeEnd":747,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/guidance/src/index.ts#L711-L747","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nconst plane = createGuidanceControlPlane();\nplane.initialize(); // missing await\nplane.startRun('task-1', 'edit'); // throws: not initialized\n// after\nconst plane = createGuidanceControlPlane();\nawait plane.initialize();\nplane.startRun('task-1', 'edit');","handlingStrategy":"validation","validationCode":"let initPromise: Promise<void> | null = null;\nfunction getPlane(plane: GuidanceControlPlane): Promise<GuidanceControlPlane> {\n  initPromise ??= plane.initialize();\n  return initPromise.then(() => plane);\n}\n// usage\nconst ready = await getPlane(plane); // every entry point awaits this\nif (ready.getBundle() === null) throw new Error('Control plane failed to load bundle');","typeGuard":"function isControlPlaneReady(plane: GuidanceControlPlane): boolean {\n  return plane.getBundle() !== null; // bundle is set only after initialize() completes\n}","tryCatchPattern":null,"preventionTips":["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"],"tags":["guidance","control-plane","lifecycle","initialization","async-await"],"backgroundTag":"component-not-initialized","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-08-22T04:17:13.399Z"}