JuliusBrussee/caveman · error · Error

${profile.display_name} not found on PATH

Error message

${profile.display_name} not found on PATH

What it means

preflightAgentNativeSetup() requires the actual agent binary (claude or codex, resolved via findAgent + binOf) to be found by which() before installing the agent-native bundle. Since the bundle configures that very agent, installing without it present is refused. Recovery of any pending transactions runs first, then this check.

Source

Thrown at packages/cli/src/index.ts:2517

  const marker = readMcpServerMarker(agent, "caveman-cloud");
  const markerKnown = !marker || sameMcpCommand(marker, pending.cloud_mcp) || sameMcpCommand(marker, pending.previous_cloud_mcp);
  const hostIsInstalled = agentNativeCloudMcpMatches(agent, pending.cloud_mcp);
  const hostIsPrevious = pending.previous_cloud_mcp
    ? agentNativeCloudMcpMatches(agent, pending.previous_cloud_mcp)
    : agentNativeCloudMcpHostAbsent(agent);
  if (!markerKnown || (!hostIsInstalled && !hostIsPrevious)) {
    throw new Error(`${agent} caveman-cloud MCP changed during interrupted removal; refusing destructive recovery`);
  }
  restoreInstalledAgentNativeBundle(agent, pending);
  unlinkSync(agentNativeBundleRemovalJournalPath(agent));
  process.stderr.write(`${mark("warn")} rolled back interrupted ${agent} agent-native bundle removal before continuing\n`);
}

function preflightAgentNativeSetup(agent: "claude" | "codex"): void {
  recoverPendingAgentNativeRemoval(agent);
  recoverPendingAgentNativeBundle(agent);
  const profile = findAgent(agent)!;
  if (!which(binOf(profile))) throw new Error(`${profile.display_name} not found on PATH`);
  const mcpBinary = nativeMcpBinaryRequired();
  const gw = gatewayURL();
  nativeProxyBinaryRequired(gw);
  withIntegrationLock(agent, () => recoverPendingNativeInstallUnlocked(agent));
  const status = nativeIntegrationStatus(agent);
  if (!status.installed) nativeMutationsFor(agent, gw, mcpBinary);
}

function ensureAgentNativeIntegration(agent: "claude" | "codex"): void {
  const status = nativeIntegrationStatus(agent);
  if (!status.installed) {
    enableNative([agent]);
    return;
  }
  if (status.state !== "installed") repairNativeAgent(agent);
}

function preflightAgentNativeBundleComponents(

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Install the agent CLI first (e.g. npm i -g @anthropic-ai/claude-code, or the codex installer)
2. If it is installed, ensure its bin dir is on PATH for this shell (restart shell, re-source profile, check version-manager shims)
3. Verify with `which claude` / `which codex` before re-running setup

import { spawnSync } from "node:child_process";
function agentBinaryOnPath(bin: string): boolean {
  return spawnSync("which", [bin]).status === 0;
}

function isAgentNotOnPathError(e: unknown): boolean {
  return e instanceof Error && e.message.endsWith("not found on PATH");
}

try {
  runCavemanSetup();
} catch (e) {
  if (isAgentNotOnPathError(e)) {
    // message names the agent — install it or fix PATH, then re-run
  } else throw e;
}

When it happens

Trigger: Running `caveman claude` agent-native setup (or setup --continuing reaching preflight) on a machine where the claude/codex CLI is not installed or not on PATH.

Common situations: Fresh machine with caveman installed via npm but the agent CLI not yet installed; agent installed via a version manager (nvm/asdf) whose shim is not on PATH in this shell; Windows binary name mismatch.

Related errors

• cannot read ${agent} agent-native bundle journal: ${(error a
• cannot read pending ${agent} agent-native bundle journal: ${
• could not install caveman-cloud MCP for ${agent}
• ${file} already exists with non-canonical content; refusing
• cave_${harness}_upstream_version_unresolvable

AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15). Data as JSON: /api/errors/6af79b190dab7c08. Report an issue: GitHub.