thedotmack/claude-mem · warning

Claude CLI preflight failed

Error message

Claude CLI preflight failed: ${err.message}

What it means

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.

Solutions

  1. Verify `claude` (Claude CLI) is installed and `claude --version` works in the worker's environment
  2. Re-authenticate the Claude CLI if auth errors appear in the logged err
  3. Check PATH for the environment running the worker (daemons/CI often have different PATH)
  4. Update Claude Code to a supported version if a CLI upgrade broke the preflight

Example fix

// before
# worker env: PATH=/usr/bin:/bin  (claude installed in ~/.local/bin)
// after
export PATH="$HOME/.local/bin:$PATH"  # before starting the worker
Defensive patterns

Strategy: fallback

Validate before calling

const { status } = spawnSync('claude', ['--version']);
if (status !== 0) console.warn('Claude CLI unavailable in this environment');

Type guard

function claudeCliAvailable(): boolean {
  const r = spawnSync('claude', ['--version'], { stdio: 'ignore' });
  return r.error === undefined && r.status === 0;
}

Try / catch

try {
  await runWorkerDependencyPreflight();
} catch (e) {
  // ensure claude on PATH / authenticated, then retry or degrade
}

Prevention

When it happens

Trigger: The Claude CLI preflight command fails to spawn, exits nonzero, times out, or otherwise throws, and classifyClaudeError returns a kind other than 'setup_required'.

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

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

AI-assisted analysis of thedotmack/claude-mem@d8bc9755e7 (2026-09-17). Data as JSON: /api/errors/b9097d82215c4dac. Report an issue: GitHub.

Appendix: source

Thrown at src/services/worker/dependency-preflight.ts:176

  return 'uvx.exe';
}

export function runWorkerDependencyPreflight(options: WorkerDependencyPreflightOptions): DependencyHealthSnapshot {
  const provider = options.settings.CLAUDE_MEM_PROVIDER || 'claude';
  const chromaEnabled = options.settings.CLAUDE_MEM_CHROMA_ENABLED !== 'false';

  if (provider === 'claude') {
    const findClaudeExecutable = options.findClaudeExecutable ?? (() => defaultFindClaudeExecutable('WORKER'));
    try {
      findClaudeExecutable();
      clearDependencyStatus('claude_cli');
    } catch (error) {
      const err = error instanceof Error ? error : new Error(String(error));
      const classified = options.classifyClaudeError(error);
      const message = classified.kind === 'setup_required'
        ? classified.message
        : `Claude CLI preflight failed: ${err.message}`;
      logger.warn('WORKER', 'Claude CLI dependency preflight failed', {
        kind: classified.kind,
      }, err);
      recordClaudeCliSetupRequired(message);
    }
  } else {
    clearDependencyStatus('claude_cli');
  }

  if (chromaEnabled) {
    const uvxCommand = resolveUvxCommand(options);
    if (hasExecutableOnPath(uvxCommand, options)) {
      clearDependencyStatus('uvx');
    } else {
      logger.warn('WORKER', 'uvx executable not found during worker dependency preflight', {
        command: uvxCommand,
      });
      recordUvxVectorSearchUnavailable(
        `uvx executable not found on effective PATH for vector search (${uvxCommand})`,

View on GitHub (pinned to d8bc9755e7)