{"record":{"id":"71275e32aec150f4","repo":"ruvnet/ruflo","slug":"failed-to-initialize-worker-manager","errorCode":null,"errorMessage":"Failed to initialize worker manager","messagePattern":"Failed to initialize worker manager","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/hooks/src/workers/session-hook.ts","lineNumber":215,"sourceCode":"}\n\nexport function setGlobalManager(manager: WorkerManager): void {\n  globalManager = manager;\n}\n\nexport async function initializeGlobalManager(projectRoot?: string): Promise<WorkerManager> {\n  if (globalManager) {\n    return globalManager;\n  }\n\n  const result = await onSessionStart({\n    projectRoot,\n    autoStart: true,\n    runInitialScan: true,\n  });\n\n  if (!result.success) {\n    throw new Error(result.error || 'Failed to initialize worker manager');\n  }\n\n  globalManager = result.manager;\n  return globalManager;\n}\n","sourceCodeStart":197,"sourceCodeEnd":221,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/hooks/src/workers/session-hook.ts#L197-L221","documentation":"Thrown by initializeGlobalManager() in @claude-flow/hooks (v3/@claude-flow/hooks/src/workers/session-hook.ts:215) when the wrapped onSessionStart() call returns success: false. The literal message is only the fallback — normally result.error carries the real reason (invalid project root, worker spawn failure, scan errors), and the throw surfaces it via `result.error || 'Failed to initialize worker manager'`.","triggerScenarios":"Calling initializeGlobalManager(projectRoot) where projectRoot is not a real directory (validateProjectRoot fails), when a background worker process fails to spawn (port conflict, missing binary), or when the initial worker scan throws. Also re-thrown on every call after a first failed attempt because globalManager stays unset.","commonSituations":"Passing a relative or wrong project root from a hook invoked in an unexpected cwd; CI sandbox where worker processes cannot spawn; Node version lacking required APIs; a first session start that half-failed leaving no cached manager.","solutions":["Inspect the thrown error's message — it is the original result.error from onSessionStart, which names the real failing step; fix that first.","Pass an absolute, existing directory as projectRoot (path.resolve it yourself) and verify it with fs.stat before calling.","Retry once after cleaning stale worker state (stop daemon, remove lock/state files under the project root).","If the fallback message appears with result.error empty, enable hook debug logging to capture which internal step returned success: false."],"exampleFix":"// before\nconst mgr = await initializeGlobalManager(projectRoot);\n\n// after\nconst absRoot = path.resolve(projectRoot);\nawait fs.access(absRoot); // fail early with a clear error\nlet mgr: WorkerManager;\ntry {\n  mgr = await initializeGlobalManager(absRoot);\n} catch (e) {\n  throw new Error(`worker manager init failed for ${absRoot}: ${(e as Error).message}`);\n}","handlingStrategy":"try-catch","validationCode":"const absRoot = path.resolve(projectRoot ?? process.cwd());\nconst st = await fs.stat(absRoot);\nif (!st.isDirectory()) throw new Error(`projectRoot is not a directory: ${absRoot}`);\nconst mgr = await initializeGlobalManager(absRoot);","typeGuard":null,"tryCatchPattern":"try {\n  mgr = await initializeGlobalManager(absRoot);\n} catch (e) {\n  // e.message is the original result.error from onSessionStart\n  logger.error('session init failed', { root: absRoot, cause: (e as Error).message });\n  throw e;\n}","preventionTips":["Always resolve and verify projectRoot before calling.","Wrap session start in your own retry-once logic for transient spawn failures.","Log result.error content — it pinpoints the failing worker step."],"tags":["initialization","session-hooks","worker-manager"],"backgroundTag":"initialization-failed","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","contentChangedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}