What causes "Failed to initialize worker manager" in ruvnet/ruflo?

Inspect the thrown error's message — it is the original result.error from onSessionStart, which names the real failing step; fix that first.

ruvnet/ruflo · error

Failed to initialize worker manager

Error message

Failed to initialize worker manager

What it means

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'`.

Source

Thrown at v3/@claude-flow/hooks/src/workers/session-hook.ts:215

}

export function setGlobalManager(manager: WorkerManager): void {
  globalManager = manager;
}

export async function initializeGlobalManager(projectRoot?: string): Promise<WorkerManager> {
  if (globalManager) {
    return globalManager;
  }

  const result = await onSessionStart({
    projectRoot,
    autoStart: true,
    runInitialScan: true,
  });

  if (!result.success) {
    throw new Error(result.error || 'Failed to initialize worker manager');
  }

  globalManager = result.manager;
  return globalManager;
}

View on GitHub (pinned to fa13ee4ad6)

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.

Example fix

// before
const mgr = await initializeGlobalManager(projectRoot);

// after
const absRoot = path.resolve(projectRoot);
await fs.access(absRoot); // fail early with a clear error
let mgr: WorkerManager;
try {
  mgr = await initializeGlobalManager(absRoot);
} catch (e) {
  throw new Error(`worker manager init failed for ${absRoot}: ${(e as Error).message}`);
}

Defensive patterns

Strategy: try-catch

Validate before calling

const absRoot = path.resolve(projectRoot ?? process.cwd());
const st = await fs.stat(absRoot);
if (!st.isDirectory()) throw new Error(`projectRoot is not a directory: ${absRoot}`);
const mgr = await initializeGlobalManager(absRoot);

Try / catch

try {
  mgr = await initializeGlobalManager(absRoot);
} catch (e) {
  // e.message is the original result.error from onSessionStart
  logger.error('session init failed', { root: absRoot, cause: (e as Error).message });
  throw e;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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