thedotmack/claude-mem · error · Error

CLAUDE_CODE_PATH is set to

Error message

CLAUDE_CODE_PATH is set to "${settings.CLAUDE_CODE_PATH}" (${probe.version}) but that CLI is too old for claude-mem — it rejects flags every memory agent spawn requires (${probe.detail}). ${updateInstructions()}

What it means

The configured CLAUDE_CODE_PATH binary exists and probes as 'incompatible': its version parses but it is too old and rejects flags that every claude-mem memory-agent spawn requires (probe.detail names the failing flags). The message includes the detected version and update instructions, because the fix is necessarily upgrading that specific binary — no fallback to other CLIs happens when an explicit path is set.

Solutions

Upgrade the binary at that exact path: npm install -g @anthropic-ai/claude-code@latest (or the package manager that owns it).
Confirm with `<path> --version` that it now meets the minimum, then re-run.
Alternatively repoint CLAUDE_CODE_PATH at a newer installed CLI, or unset it so discovery picks the best candidate.

Example fix

# before
CLAUDE_CODE_PATH=/usr/local/bin/claude  # v0.x, rejects required flags

# after
npm install -g @anthropic-ai/claude-code@latest
# /usr/local/bin/claude --version now reports a capable version

Defensive patterns

Strategy: validation

Validate before calling

import { execFileSync } from 'child_process';
const v = execFileSync(claudePath, ['--version'], { encoding: 'utf8' }).trim();
const [major, minor] = v.replace(/^v/, '').split('.').map(Number);
if (major < MIN_MAJOR || (major === MIN_MAJOR && minor < MIN_MINOR)) {
  throw new Error(`CLI ${v} at ${claudePath} is below claude-mem minimum ${MIN_MAJOR}.${MIN_MINOR}`);
}

Prevention

When pinning CLAUDE_CODE_PATH, record the minimum CLI version next to the pin in docs.
Re-verify `<path> --version` after every claude-mem upgrade, since required flags can grow.
Let the auto-discovery path run occasionally to see if a newer candidate exists.

When it happens

Trigger: CLAUDE_CODE_PATH pinned to an old npm-installed claude-code while claude-mem's SDK options grew new required flags; a system package (brew/apt) lagging behind; a version-pinned corporate install.

Common situations: claude-mem upgraded to a release needing newer CLI flags than the pinned one; users who set CLAUDE_CODE_PATH months ago and forgot; CI images caching an old CLI.

Related errors

AI-assisted analysis of thedotmack/claude-mem@e2d1df569a (2026-08-20). Data as JSON: /api/errors/5996479db8ffbe80. Report an issue: GitHub.

Appendix: source

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

    const configuredPath = expandTilde(settings.CLAUDE_CODE_PATH, _internals.homedir());
    if (!_internals.existsSync(configuredPath)) {
      throw new Error(
        `CLAUDE_CODE_PATH is set to "${settings.CLAUDE_CODE_PATH}" but the file does not exist.`
      );
    }

    const probe = probeCandidate(configuredPath);
    if (probe.kind === 'capable') {
      logger.info(logComponent, `Using configured CLAUDE_CODE_PATH: ${configuredPath} (${probe.version})`);
      cachedResolution = {
        path: configuredPath,
        version: probe.version,
        expiresAtMs: Date.now() + RESOLUTION_CACHE_TTL_MS,
      };
      return configuredPath;
    }
    if (probe.kind === 'incompatible') {
      throw new Error(
        `CLAUDE_CODE_PATH is set to "${settings.CLAUDE_CODE_PATH}" (${probe.version}) but that CLI is too old for claude-mem — ` +
        `it rejects flags every memory agent spawn requires (${probe.detail}). ${updateInstructions()}`
      );
    }
    if (looksLikeDesktopAppPath(configuredPath)) {
      throw new Error(
        `Found desktop app at "${settings.CLAUDE_CODE_PATH}" but it doesn't support headless mode. ` +
        `Install Claude Code CLI: npm install -g @anthropic-ai/claude-code`
      );
    }
    throw new Error(
      `CLAUDE_CODE_PATH is set to "${settings.CLAUDE_CODE_PATH}" but it failed the --version check (${probe.detail}). ` +
      `Ensure this is a working Claude Code CLI binary.`
    );
  }

  // --- 2. Probe every discovered candidate ---------------------------------
  const capable: Array<{ path: string; version: string; key: [number, number, number]; order: number }> = [];

View on GitHub (pinned to e2d1df569a)