{"record":{"id":"b9097d82215c4dac","repo":"thedotmack/claude-mem","slug":"claude-cli-preflight-failed-err-message","errorCode":null,"errorMessage":"Claude CLI preflight failed: ${err.message}","messagePattern":"Claude CLI preflight failed: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"src/services/worker/dependency-preflight.ts","lineNumber":176,"sourceCode":"  return 'uvx.exe';\n}\n\nexport function runWorkerDependencyPreflight(options: WorkerDependencyPreflightOptions): DependencyHealthSnapshot {\n  const provider = options.settings.CLAUDE_MEM_PROVIDER || 'claude';\n  const chromaEnabled = options.settings.CLAUDE_MEM_CHROMA_ENABLED !== 'false';\n\n  if (provider === 'claude') {\n    const findClaudeExecutable = options.findClaudeExecutable ?? (() => defaultFindClaudeExecutable('WORKER'));\n    try {\n      findClaudeExecutable();\n      clearDependencyStatus('claude_cli');\n    } catch (error) {\n      const err = error instanceof Error ? error : new Error(String(error));\n      const classified = options.classifyClaudeError(error);\n      const message = classified.kind === 'setup_required'\n        ? classified.message\n        : `Claude CLI preflight failed: ${err.message}`;\n      logger.warn('WORKER', 'Claude CLI dependency preflight failed', {\n        kind: classified.kind,\n      }, err);\n      recordClaudeCliSetupRequired(message);\n    }\n  } else {\n    clearDependencyStatus('claude_cli');\n  }\n\n  if (chromaEnabled) {\n    const uvxCommand = resolveUvxCommand(options);\n    if (hasExecutableOnPath(uvxCommand, options)) {\n      clearDependencyStatus('uvx');\n    } else {\n      logger.warn('WORKER', 'uvx executable not found during worker dependency preflight', {\n        command: uvxCommand,\n      });\n      recordUvxVectorSearchUnavailable(\n        `uvx executable not found on effective PATH for vector search (${uvxCommand})`,","sourceCodeStart":158,"sourceCodeEnd":194,"githubUrl":"https://github.com/thedotmack/claude-mem/blob/d8bc9755e74915e5c3b999181e10a67c889bce2a/src/services/worker/dependency-preflight.ts#L158-L194","documentation":"runWorkerDependencyPreflight validates that the Claude CLI works before the worker starts. When the preflight check throws and the error is not classified as 'setup_required', it logs this warning with the raw error message and records that Claude CLI setup is required.","triggerScenarios":"The Claude CLI preflight command fails to spawn, exits nonzero, times out, or otherwise throws, and classifyClaudeError returns a kind other than 'setup_required'.","commonSituations":"Claude Code not installed or not on PATH; authentication expired causing an unexpected CLI error; CLI version change altering output; restricted environment blocking process spawn.","solutions":["Verify `claude` (Claude CLI) is installed and `claude --version` works in the worker's environment","Re-authenticate the Claude CLI if auth errors appear in the logged err","Check PATH for the environment running the worker (daemons/CI often have different PATH)","Update Claude Code to a supported version if a CLI upgrade broke the preflight"],"exampleFix":"// before\n# worker env: PATH=/usr/bin:/bin  (claude installed in ~/.local/bin)\n// after\nexport PATH=\"$HOME/.local/bin:$PATH\"  # before starting the worker","handlingStrategy":"fallback","validationCode":"const { status } = spawnSync('claude', ['--version']);\nif (status !== 0) console.warn('Claude CLI unavailable in this environment');","typeGuard":"function claudeCliAvailable(): boolean {\n  const r = spawnSync('claude', ['--version'], { stdio: 'ignore' });\n  return r.error === undefined && r.status === 0;\n}","tryCatchPattern":"try {\n  await runWorkerDependencyPreflight();\n} catch (e) {\n  // ensure claude on PATH / authenticated, then retry or degrade\n}","preventionTips":["Install and authenticate Claude CLI before starting the worker","Set PATH explicitly in daemon/CI environments","Pin a supported Claude Code version"],"tags":["claude-cli","preflight","dependency-check","worker"],"backgroundTag":"missing-dependency","analyzedSha":"d8bc9755e74915e5c3b999181e10a67c889bce2a","analyzedAt":"2026-09-17T16:40:26.182Z","contentChangedAt":"2026-09-17T16:40:26.182Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}