{"record":{"id":"31fac0b4192089a9","repo":"thedotmack/claude-mem","slug":"worker-failed-to-start-before-hook-handler-will-p","errorCode":null,"errorMessage":"Worker failed to start before hook, handler will proceed gracefully","messagePattern":"Worker failed to start before hook, handler will proceed gracefully","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"src/services/worker-service.ts","lineNumber":1332,"sourceCode":"\n    case 'hook': {\n      // IO discipline: this case is the entry point to the hook execution path.\n      // Once hookCommand is invoked, src/shared/hook-io.ts owns all\n      // stdout/stderr/exit. The pre-hookCommand error paths below (missing args,\n      // worker failed to start) are CLI-style: console.error + exit 1 is\n      // acceptable because they occur BEFORE the buffered window opens.\n      const platform = process.argv[3];\n      const event = process.argv[4];\n      if (!platform || !event) {\n        console.error('Usage: claude-mem hook <platform> <event>');\n        console.error('Platforms: claude-code, codex, cursor, antigravity-cli, raw');\n        console.error('Events: context, session-init, observation, summarize, user-message');\n        process.exit(1);\n      }\n\n      const workerStartResult = await ensureWorkerStarted(port);\n      if (workerStartResult === 'dead') {\n        logger.warn('SYSTEM', 'Worker failed to start before hook, handler will proceed gracefully');\n      }\n\n      const { hookCommand } = await import('../cli/hook-command.js');\n      await hookCommand(platform, event);\n      break;\n    }\n\n    case 'generate': {\n      const dryRun = process.argv.includes('--dry-run');\n      const { generateClaudeMd } = await import('../cli/claude-md-commands.js');\n      const result = await generateClaudeMd(dryRun);\n      process.exit(result);\n      break;\n    }\n\n    case 'clean': {\n      const dryRun = process.argv.includes('--dry-run');\n      const { cleanClaudeMd } = await import('../cli/claude-md-commands.js');","sourceCodeStart":1314,"sourceCodeEnd":1350,"githubUrl":"https://github.com/thedotmack/claude-mem/blob/e2d1df569a8f04075d40e92461128ece7cf04c82/src/services/worker-service.ts#L1314-L1350","documentation":"Before dispatching a hook event (context, observation, summarize, ...), the hook command calls ensureWorkerStarted(). If that returns 'dead' — spawn failed, Windows cooldown skip, or port conflict without health — this warning fires. The hook then proceeds without the worker, so this event's memory capture is skipped rather than blocking the user's session.","triggerScenarios":"Worker spawn fails (missing runtime, permissions, antivirus on Windows); shouldSkipSpawnOnWindows() suppresses spawn within the 2-minute cooldown after a prior failure; port occupied by a non-worker process.","commonSituations":"Windows machines where a previous spawn failed and hooks keep firing inside the cooldown; broken node/bun install; corporate security software blocking the daemon; disk-full preventing log/db writes at startup.","solutions":["Run `claude-mem start` manually and read the worker log to see the actual spawn failure","On Windows, wait out the 2-minute spawn cooldown before retrying (or delete the cooldown marker once the root cause is fixed)","Free the occupied port or move claude-mem to another one, then retry the hook-triggering action"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"const result = await ensureWorkerStarted(port);\nif (result === 'dead') {\n  // proceed without worker; schedule a manual start instead of retrying in the hot path\n  console.warn('worker unavailable — hook will run without memory capture');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Design hooks to degrade gracefully — never block the user's session on worker availability","Start the worker at boot/session start so hooks do not lazy-spawn under pressure","On Windows, fix the root spawn failure instead of hammering hooks inside the cooldown"],"tags":["hooks","worker","spawn","graceful-degradation"],"backgroundTag":"service-startup-failure","analyzedSha":"e2d1df569a8f04075d40e92461128ece7cf04c82","analyzedAt":"2026-08-20T23:58:13.836Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}