{"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":2837,"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":2819,"sourceCodeEnd":2855,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/cli/src/index.ts#L2819-L2855","documentation":"The preflight for agent-native setup requires the agent's executable (claude or codex) to be resolvable on PATH. If which(binOf(profile)) returns null, the agent binary cannot be found and setup cannot proceed, so it throws naming the agent's display name.","triggerScenarios":"Running `caveman setup claude` or `caveman setup codex` when the corresponding agent binary is not installed or not on the current PATH.","commonSituations":"Agent installed via GUI but CLI shim not on PATH; running in a container/CI without the agent installed; PATH differs between shells (e.g. nvm/volta shims missing in non-interactive shells); typo'd install.","solutions":["Install the missing agent CLI (e.g. `npm install -g @anthropic-ai/claude-code` or codex)","Add the agent binary's directory to PATH in the shell running the setup command","Verify with `which claude` / `which codex` and fix the shell profile accordingly"],"exampleFix":"// before\nthrow new Error(`${profile.display_name} not found on PATH`);\n// after\n// fix environment before running:\n// export PATH=\"$PATH:/usr/local/bin\" && caveman setup claude","handlingStrategy":"fallback","validationCode":"import { which } from './which-or-shim';\nif (!which('claude')) console.error('claude not on PATH; install it or fix PATH before running setup.');\nif (!which('codex')) console.error('codex not on PATH; install it or fix PATH before running setup.');","typeGuard":null,"tryCatchPattern":"try {\n  runSetup(agent);\n} catch (e) {\n  if (String(e.message).endsWith('not found on PATH')) {\n    // install the agent CLI or export PATH to include its bin directory, then retry\n  }\n}","preventionTips":["Verify `which claude` / `which codex` succeeds before running setup","In CI/containers, install the agent CLI as a setup step","Watch for PATH differences between interactive and non-interactive shells (nvm/volta)"],"tags":["path","cli","dependency-missing","setup"],"backgroundTag":"command-not-found","analyzedSha":"3ee70a102609e550bd2e68004bf5990a9341c851","analyzedAt":"2026-09-20T15:53:39.229Z","contentChangedAt":"2026-09-20T15:53:39.229Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}