thedotmack/claude-mem · error · Error

CLAUDE_CODE_PATH is set to "${settings.CLAUDE_CODE_PATH}" bu

Error message

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.

What it means

Thrown by findClaudeExecutable when CLAUDE_CODE_PATH exists, is neither 'capable', 'incompatible', nor a desktop-app path — the probe's --version check failed for some other reason (probe.detail holds the stderr/output). The binary is present but unrecognizable as a working Claude Code CLI.

Source

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

        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 }> = [];
  const incompatible: Array<{ path: string; version: string; detail: string }> = [];

  const candidates = discoverCandidates();
  for (let order = 0; order < candidates.length; order++) {
    const candidate = candidates[order];
    const probe = probeCandidate(candidate);

    if (probe.kind === 'capable') {
      capable.push({ path: candidate, version: probe.version, key: parseVersionKey(probe.version), order });
      continue;
    }

View on GitHub (pinned to d768ba3643)

Solutions

Run `<path> --version` manually to reproduce and read probe.detail.
Ensure the file is executable and is the real Claude Code CLI binary.
Reinstall the CLI: `npm install -g @anthropic-ai/claude-code` and repoint the setting.
If unsure, remove CLAUDE_CODE_PATH to let PATH auto-discovery find a working binary.

Defensive patterns

Strategy: try-catch

Validate before calling

// Manually probe to get a clear failure before worker startup
const probe = probeCandidate(configuredPath);
if (probe.kind !== 'capable' && probe.kind !== 'incompatible') {
  throw new Error(`CLAUDE_CODE_PATH failed --version: ${probe.detail}`);
}

Try / catch

try {
  return findClaudeExecutable('SDK');
} catch (err) {
  if (err instanceof Error && /failed the --version check/.test(err.message)) {
    logger.error('SDK', err.message);
    // suggest reinstall or unset CLAUDE_CODE_PATH
  }
  throw err;
}

Prevention

Run `<path> --version` to confirm the binary works before setting it.
Ensure the file is executable and is the genuine CLI binary.
Reinstall the CLI if the probe output is unparseable.

When it happens

Trigger: CLAUDE_CODE_PATH points to a file that exists but `claude --version` (the probe) failed or returned unparseable output; probe.kind is the fallback failure case.

Common situations: Path points to a non-executable, a shell script wrapper that errors, a broken/partial install, a binary for a different platform, or a file that exists but isn't the Claude CLI at all.

Related errors

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