{"record":{"id":"fa2891182591829a","repo":"JuliusBrussee/caveman","slug":"caveman-mcp-not-found-run-caveman-setup-instal","errorCode":null,"errorMessage":"caveman-mcp not found; run `caveman setup --install`","messagePattern":"caveman-mcp not found; run `caveman setup --install`","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/index.ts","lineNumber":6986,"sourceCode":"function durableUnlink(path: string): void {\n  try {\n    unlinkSync(path);\n    fsyncParentDirectory(path);\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code !== \"ENOENT\") throw error;\n  }\n}\n\nfunction parseJsonFileObject(path: string, bytes: Buffer | null): Record<string, unknown> {\n  if (!bytes || bytes.length === 0) return {};\n  const parsed = JSON.parse(bytes.toString(\"utf8\"));\n  if (!parsed || typeof parsed !== \"object\" || Array.isArray(parsed)) throw new Error(`${path} is not a JSON object`);\n  return parsed as Record<string, unknown>;\n}\n\nfunction nativeMcpBinaryRequired(): string {\n  const compatible = probeMcpBinary();\n  if (!compatible) throw new Error(\"caveman-mcp not found; run `caveman setup --install`\");\n  if (!compatible.probe.current) throw new Error(`caveman-mcp ${compatible.probe.version} lacks current mcp_recovery capability; run \\`caveman setup --install\\``);\n  return compatible.binary;\n}\n\nfunction nativeProxyBinaryRequired(gw: string): void {\n  if (wrapMode(gw) !== \"local\") return;\n  const binary = resolveGoBin(\"caveman-proxy\", \"CAVEMAN_PROXY_BIN\");\n  if (!binary) throw new Error(\"caveman-proxy not found; run `caveman setup --install`\");\n  const probe = probeVersionedBinary(binary, \"native_runtime_v1\");\n  if (!probe.current) throw new Error(`caveman-proxy ${probe.version} lacks current native_runtime_v1 capability; run \\`caveman setup --install\\``);\n}\n\nfunction nativeHostProbe(agent: AgentProfile): { binary: string | null; launchable: boolean; version: string | null; error: string | null } {\n  const binary = which(binOf(agent));\n  if (!binary) return { binary: null, launchable: false, version: null, error: \"binary_not_found\" };\n  try {\n    const invocation = portableInvocation(binary, [\"--version\"]);\n    const out = spawnSync(invocation.command, invocation.args, { encoding: \"utf8\", timeout: 3000 });","sourceCodeStart":6968,"sourceCodeEnd":7004,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/cli/src/index.ts#L6968-L7004","documentation":"Thrown by nativeMcpBinaryRequired when the bundled/installed caveman-mcp binary cannot be found or probed as compatible. The CLI's native MCP mode depends on this companion binary being installed; without it, MCP management cannot proceed. A related error covers a found binary that lacks the required mcp_recovery capability version.","triggerScenarios":"probeMcpBinary() returns a falsy/compatible=false result because the caveman-mcp executable is not on the expected install path or PATH during native MCP operations.","commonSituations":"Fresh clone or CI environment where `caveman setup --install` was never run; the binary was deleted by a cleanup script; npm global install missing; running from a different machine/container without setup.","solutions":["Run `caveman setup --install` to install/update the caveman-mcp binary","If a partial install exists, reinstall: remove the old binary and re-run setup","Verify the install location is on PATH or in the expected plugin directory","Check the probe: if the error mentions missing mcp_recovery capability, the binary is outdated — reinstall to update it"],"exampleFix":"// before\n$ caveman mcp list\ncaveman-mcp not found; run `caveman setup --install`\n// after\n$ caveman setup --install\n$ caveman mcp list","handlingStrategy":"try-catch","validationCode":"import { execFileSync } from \"node:child_process\";\nfunction cavemanMcpInstalled(): boolean {\n  try { execFileSync(\"caveman-mcp\", [\"--version\"], { stdio: \"ignore\" }); return true; } catch { return false;\n  }\n}","typeGuard":"null","tryCatchPattern":"try {\n  runNativeMcpCommand();\n} catch (e) {\n  if (String(e.message).includes(\"caveman-mcp not found\")) {\n    execFileSync(\"caveman\", [\"setup\", \"--install\"], { stdio: \"inherit\" });\n    runNativeMcpCommand();\n  }\n}","preventionTips":["Always run `caveman setup --install` after installing or updating the CLI","Include setup in CI/bootstrap scripts before any MCP commands","Verify the binary exists on PATH when moving between machines or containers","Reinstall if the error mentions a missing mcp_recovery capability (outdated binary)"],"tags":["missing-binary","mcp","setup","dependency"],"backgroundTag":"missing-dependency","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"}