{"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":null,"httpStatus":null,"severity":"error","filePath":"packages/cli/src/index.ts","lineNumber":6005,"sourceCode":"    writeFileSync(temp, bytes, { mode });\n    renameSync(temp, path);\n    chmodSync(path, mode);\n  } catch (error) {\n    try { unlinkSync(temp); } catch { /* no partial */ }\n    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":5987,"sourceCodeEnd":6023,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/27d5a3981a347890211bb1bf2439e5c821a63bc9/packages/cli/src/index.ts#L5987-L6023","documentation":"nativeMcpBinaryRequired resolves the caveman-mcp Go binary (via probeMcpBinary, honoring overrides) and requires it to exist. Missing binary means the native MCP server that agents connect to cannot be launched, so setup fails fast with the remediation command.","triggerScenarios":"Any native setup/registration path calling nativeMcpBinaryRequired when caveman-mcp is absent from PATH/resolved locations and no CAVEMAN_MCP_BIN-style override points to it.","commonSituations":"Fresh machine without `caveman setup --install`; ~/go/bin not on PATH after install; binary deleted by cleanup; npm-installed CLI used before Go binaries were built.","solutions":["Run `caveman setup --install` to build/install the Go binaries","Ensure the Go bin directory (go env GOBIN or ~/go/bin) is on PATH","Point the environment override at an existing caveman-mcp binary if installed elsewhere","Verify with `which caveman-mcp` and `caveman-mcp --version`"],"exampleFix":"# before\ncaveman setup --agent-native claude  # Error: caveman-mcp not found\n\n# after\ncaveman setup --install\ncaveman setup --agent-native claude","handlingStrategy":"validation","validationCode":"import { which } from \"caveman\";\nif (!which(\"caveman-mcp\")) {\n  throw new Error(\"caveman-mcp missing; run `caveman setup --install` first\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  nativeMcpBinaryRequired();\n} catch (error) {\n  if (/caveman-mcp not found/.test((error as Error).message)) {\n    throw new Error(\"precondition failed: run `caveman setup --install` and re-run this step\", { cause: error });\n  }\n  throw error;  // version-capability failures need a binary upgrade, same command\n}","preventionTips":["Run `caveman setup --install` as the first step on any new machine/CI image","Keep $(go env GOPATH)/bin on PATH in shell profiles and CI","Verify `caveman-mcp --version` succeeds after CLI upgrades"],"tags":["binary-missing","setup","mcp","go-binaries"],"backgroundTag":null,"analyzedSha":"27d5a3981a347890211bb1bf2439e5c821a63bc9","analyzedAt":"2026-08-15T09:26:11.751Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}