Claude executable not found. Please either: 1. Add "claude"

Error message

Claude executable not found. Please either:
1. Add "claude" to your system PATH, or
2. Set CLAUDE_CODE_PATH in ~/.claude-mem/settings.json

What it means

Thrown by findClaudeExecutable when no Claude CLI was found at all: no CLAUDE_CODE_PATH set and discoverCandidates() returned an empty list (or all were skipped, leaving no incompatible entries either). This is the total absence case — neither capable nor incompatible candidates exist.

Source

Thrown at src/shared/find-claude-executable.ts:389

    cachedResolution = {
      path: winner.path,
      version: winner.version,
      expiresAtMs: Date.now() + RESOLUTION_CACHE_TTL_MS,
    };
    return winner.path;
  }

  if (incompatible.length > 0) {
    const lines = incompatible
      .map((entry) => `  - ${entry.path} (${entry.version}) — ${entry.detail}`)
      .join('\n');
    throw new Error(
      `Every Claude CLI found is too old for claude-mem (each rejects flags the memory agent passes on every spawn):\n` +
      `${lines}\n${updateInstructions()}`
    );
  }

  throw new Error(
    'Claude executable not found. Please either:\n' +
    '1. Add "claude" to your system PATH, or\n' +
    '2. Set CLAUDE_CODE_PATH in ~/.claude-mem/settings.json'
  );
}

View on GitHub (pinned to d768ba3643)

Solutions

Install the CLI: `npm install -g @anthropic-ai/claude-code`.
Ensure the install directory is on PATH (`echo $PATH`, `which claude`).
If installed in a custom location, set CLAUDE_CODE_PATH in ~/.claude-mem/settings.json to its absolute path.

Example fix

// before: claude not installed / not on PATH
// after
npm install -g @anthropic-ai/claude-code
# or set in ~/.claude-mem/settings.json: "CLAUDE_CODE_PATH": "/usr/local/bin/claude"

Defensive patterns

Strategy: validation

Validate before calling

import { existsSync } from 'fs';
function claudeAvailable(): boolean {
  try { return existsSync(require('child_process').execSync('which claude', { encoding: 'utf8' }).trim()); }
  catch { return false; }
}
if (!claudeAvailable() && !settings.CLAUDE_CODE_PATH) {
  throw new Error('Claude CLI not installed — run npm install -g @anthropic-ai/claude-code');
}

Try / catch

try {
  return findClaudeExecutable('SDK');
} catch (err) {
  if (err instanceof Error && /Claude executable not found/.test(err.message)) {
    logger.error('SDK', err.message);
    // halt startup with install guidance
  }
  throw err;
}

Prevention

Install @anthropic-ai/claude-code as a prerequisite in setup scripts.
Ensure the install dir is on PATH in all environments (CI, shells, services).
Document CLAUDE_CODE_PATH as the escape hatch for custom locations.

When it happens

Trigger: No `claude` on PATH and CLAUDE_CODE_PATH unset; discoverCandidates() yields nothing on any known install location.

Common situations: Fresh machine without Claude Code installed; PATH not exposing the install; Claude installed under a non-standard location not searched by discoverCandidates.

Related errors

AI-assisted analysis of thedotmack/claude-mem@d768ba3643 (2026-08-12). Data as JSON: /api/errors/f24276ed9b47b859. Report an issue: GitHub.