{"record":{"id":"c27c049f5c189573","repo":"thedotmack/claude-mem","slug":"worker-shutdown-failed-message","errorCode":null,"errorMessage":"Worker shutdown failed: ${message}","messagePattern":"Worker shutdown failed: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/npx-cli/commands/install.ts","lineNumber":1881,"sourceCode":"      spinner?.error('Running worker did not stop; refusing to overwrite its live configuration.');\n      installerError(ErrorSeverity.ABORT, {\n        component: 'worker-shutdown',\n        phase,\n        cause: new Error('The existing worker did not stop within 10 seconds.'),\n        remediation: 'Run `npx claude-mem stop`, verify it exits, then run `npx claude-mem install` again.',\n      }, summary);\n    }\n\n    const stopMessage = result.workerWasRunning\n      ? 'Stopped running worker before configuration cutover.'\n      : 'No worker running — proceeding.';\n    if (spinner) spinner.stop(stopMessage);\n    else if (result.workerWasRunning) log.info(stopMessage);\n  } catch (error: unknown) {\n    if (error instanceof InstallAbortError) throw error;\n    const message = error instanceof Error ? error.message : String(error);\n    if (spinner) spinner.error(`Worker shutdown failed: ${message}`);\n    else console.warn('[install] Worker shutdown failed:', message);\n    installerError(ErrorSeverity.ABORT, {\n      component: 'worker-shutdown',\n      phase,\n      cause: error,\n      remediation: 'Run `npx claude-mem stop`, verify it exits, then run `npx claude-mem install` again.',\n    }, summary);\n  }\n}\n\nfunction validateNonInteractiveProvider(\n  options: InstallOptions,\n  summary: InstallSummary,\n): void {\n  if (isInteractive) return;\n\n  if (!options.provider) {\n    installerError(ErrorSeverity.ABORT, {\n      component: 'provider-selection',","sourceCodeStart":1863,"sourceCodeEnd":1899,"githubUrl":"https://github.com/thedotmack/claude-mem/blob/8bc631a71a487424b866756e43a6efa4574cc66b/src/npx-cli/commands/install.ts#L1863-L1899","documentation":"During `npx claude-mem install`, the installer attempts to stop a running worker service before completing installation. If the shutdown step throws any error (other than InstallAbortError, which is re-thrown), the installer logs 'Worker shutdown failed: <message>' and records an installerError with severity ABORT, component 'worker-shutdown', with remediation pointing at `npx claude-mem stop`. This is fatal because a worker that cannot be shut down can leave stale processes or port conflicts that corrupt the install.","triggerScenarios":"A worker process is running during install and the shutdown call throws — the worker port is unreachable in a way that raises, the process refuses to stop, an IPC/socket error occurs during the stop request, or an unexpected exception escapes the shutdown routine inside the install command.","commonSituations":"Stale worker from a previously crashed session holding CLAUDE_MEM_WORKER_PORT; worker process hung and unresponsive; permission issues killing the worker process; version mismatch where the running worker no longer understands the shutdown protocol; antivirus/firewall interfering with the stop request.","solutions":["Run `npx claude-mem stop` and verify the worker process exits.","Re-run `npx claude-mem install` after confirming the worker is gone.","If the process will not die, kill it manually (kill <pid> on macOS/Linux, taskkill /F /PID <pid> on Windows).","Check nothing else is bound to CLAUDE_MEM_WORKER_PORT; change the port in settings if there is a conflict.","Retry the install; if it persists, capture the underlying message from the installerError output for a bug report."],"exampleFix":"// before\nnpx claude-mem install   // fails: Worker shutdown failed: ...\n// after\nnpx claude-mem stop       # verify it exits\nnpx claude-mem install","handlingStrategy":"try-catch","validationCode":"const port = 37777; // or settings CLAUDE_MEM_WORKER_PORT\nconst res = await fetch(`http://127.0.0.1:${port}/health`).catch(() => null);\nif (res && res.ok) console.log('worker running — run npx claude-mem stop before install');","typeGuard":"function isAbort(e: unknown): e is InstallAbortError { return e instanceof InstallAbortError; }","tryCatchPattern":"try {\n  await shutdownWorkerAndWait(port, 10000);\n} catch (error) {\n  if (error instanceof InstallAbortError) throw error;\n  console.error('Worker shutdown failed:', error instanceof Error ? error.message : String(error));\n  // remediation: npx claude-mem stop, verify exit, retry install\n}","preventionTips":["Run `npx claude-mem stop` before upgrading/reinstalling and confirm the process exited.","Watch for orphaned worker processes after crashes and kill them.","Keep CLAUDE_MEM_WORKER_PORT free of conflicting services.","After a failed shutdown, verify the port is released before retrying install."],"tags":["worker","shutdown","install","process-lifecycle"],"backgroundTag":"invalid-state-transition","analyzedSha":"8bc631a71a487424b866756e43a6efa4574cc66b","analyzedAt":"2026-09-09T10:47:06.009Z","contentChangedAt":"2026-09-09T10:47:06.009Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}