{"record":{"id":"6af79b190dab7c08","repo":"JuliusBrussee/caveman","slug":"profile-display-name-not-found-on-path","errorCode":null,"errorMessage":"${profile.display_name} not found on PATH","messagePattern":"(.+?) not found on PATH","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/index.ts","lineNumber":2517,"sourceCode":"  const marker = readMcpServerMarker(agent, \"caveman-cloud\");\n  const markerKnown = !marker || sameMcpCommand(marker, pending.cloud_mcp) || sameMcpCommand(marker, pending.previous_cloud_mcp);\n  const hostIsInstalled = agentNativeCloudMcpMatches(agent, pending.cloud_mcp);\n  const hostIsPrevious = pending.previous_cloud_mcp\n    ? agentNativeCloudMcpMatches(agent, pending.previous_cloud_mcp)\n    : agentNativeCloudMcpHostAbsent(agent);\n  if (!markerKnown || (!hostIsInstalled && !hostIsPrevious)) {\n    throw new Error(`${agent} caveman-cloud MCP changed during interrupted removal; refusing destructive recovery`);\n  }\n  restoreInstalledAgentNativeBundle(agent, pending);\n  unlinkSync(agentNativeBundleRemovalJournalPath(agent));\n  process.stderr.write(`${mark(\"warn\")} rolled back interrupted ${agent} agent-native bundle removal before continuing\\n`);\n}\n\nfunction preflightAgentNativeSetup(agent: \"claude\" | \"codex\"): void {\n  recoverPendingAgentNativeRemoval(agent);\n  recoverPendingAgentNativeBundle(agent);\n  const profile = findAgent(agent)!;\n  if (!which(binOf(profile))) throw new Error(`${profile.display_name} not found on PATH`);\n  const mcpBinary = nativeMcpBinaryRequired();\n  const gw = gatewayURL();\n  nativeProxyBinaryRequired(gw);\n  withIntegrationLock(agent, () => recoverPendingNativeInstallUnlocked(agent));\n  const status = nativeIntegrationStatus(agent);\n  if (!status.installed) nativeMutationsFor(agent, gw, mcpBinary);\n}\n\nfunction ensureAgentNativeIntegration(agent: \"claude\" | \"codex\"): void {\n  const status = nativeIntegrationStatus(agent);\n  if (!status.installed) {\n    enableNative([agent]);\n    return;\n  }\n  if (status.state !== \"installed\") repairNativeAgent(agent);\n}\n\nfunction preflightAgentNativeBundleComponents(","sourceCodeStart":2499,"sourceCodeEnd":2535,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/27d5a3981a347890211bb1bf2439e5c821a63bc9/packages/cli/src/index.ts#L2499-L2535","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install the agent CLI first (e.g. npm i -g @anthropic-ai/claude-code, or the codex installer)","If it is installed, ensure its bin dir is on PATH for this shell (restart shell, re-source profile, check version-manager shims)","Verify with `which claude` / `which codex` before re-running setup"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"import { spawnSync } from \"node:child_process\";\nfunction agentBinaryOnPath(bin: string): boolean {\n  return spawnSync(\"which\", [bin]).status === 0;\n}","typeGuard":"function isAgentNotOnPathError(e: unknown): boolean {\n  return e instanceof Error && e.message.endsWith(\"not found on PATH\");\n}","tryCatchPattern":"try {\n  runCavemanSetup();\n} catch (e) {\n  if (isAgentNotOnPathError(e)) {\n    // message names the agent — install it or fix PATH, then re-run\n  } else throw e;\n}","preventionTips":["Install the agent CLI (claude/codex) before running caveman agent-native setup","Verify `which claude` / `which codex` in the same shell you run caveman from","Watch out for version-manager shims (nvm, asdf) missing from non-interactive shells"],"tags":["install","path","preflight","agent-native"],"backgroundTag":null,"analyzedSha":"27d5a3981a347890211bb1bf2439e5c821a63bc9","analyzedAt":"2026-08-15T09:26:11.751Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}