{"record":{"id":"35665f7a38c7414f","repo":"JuliusBrussee/caveman","slug":"caveman-proxy-not-found-run-caveman-setup-inst","errorCode":null,"errorMessage":"caveman-proxy not found; run `caveman setup --install`","messagePattern":"caveman-proxy not found; run `caveman setup --install`","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cli/src/index.ts","lineNumber":6013,"sourceCode":"\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 });\n    if (out.error) return { binary, launchable: false, version: null, error: boundedHookString(out.error.message, 240) ?? \"version_probe_failed\" };\n    const value = `${out.stdout ?? \"\"} ${out.stderr ?? \"\"}`.trim();\n    if (out.status !== 0) return { binary, launchable: false, version: value ? value.slice(0, 160) : null, error: `version_probe_exit_${out.status ?? \"unknown\"}` };\n    return { binary, launchable: true, version: value ? value.slice(0, 160) : null, error: null };\n  } catch {\n    return { binary, launchable: false, version: null, error: \"version_probe_failed\" };\n  }\n}","sourceCodeStart":5995,"sourceCodeEnd":6031,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/27d5a3981a347890211bb1bf2439e5c821a63bc9/packages/cli/src/index.ts#L5995-L6031","documentation":"nativeProxyBinaryRequired applies only when wrapMode(gw) is \"local\": local wrapping needs the caveman-proxy Go binary. resolveGoBin(\"caveman-proxy\", \"CAVEMAN_PROXY_BIN\") returning nothing means the proxy cannot be spawned, so the native runtime setup aborts with the remediation command. (A separate message covers the version-capability mismatch.)","triggerScenarios":"Choosing a local wrap mode gateway in setup while caveman-proxy is not installed: fresh environment, Go bin dir missing from PATH, CAVEMAN_PROXY_BIN pointing at a deleted path, non-local modes skip this entirely.","commonSituations":"First-time local-mode setup without running --install; PATH reset in CI or after shell migration; binary pruned by disk cleanup.","solutions":["Run `caveman setup --install` to install caveman-proxy","Add the Go bin directory to PATH (e.g. export PATH=\"$PATH:$(go env GOPATH)/bin\")","Set CAVEMAN_PROXY_BIN to an absolute existing caveman-proxy binary if installed at a custom location","Or switch the gateway to a non-local wrap mode which does not require the proxy"],"exampleFix":"# before\ncaveman setup --agent-native codex  # Error: caveman-proxy not found (local wrap mode)\n\n# after\nexport PATH=\"$PATH:$HOME/go/bin\"\ncaveman setup --install\ncaveman setup --agent-native codex","handlingStrategy":"validation","validationCode":"import { which } from \"caveman\";\nif (wrapMode(gateway) === \"local\" && !process.env.CAVEMAN_PROXY_BIN && !which(\"caveman-proxy\")) {\n  throw new Error(\"local wrap mode requires caveman-proxy; run `caveman setup --install` or pick a non-local gateway\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  nativeProxyBinaryRequired(gateway);\n} catch (error) {\n  if (/caveman-proxy not found/.test((error as Error).message)) {\n    // either provision the binary or fall back to a gateway mode that does not need it\n    await ensureGoBinariesInstalled();\n    nativeProxyBinaryRequired(gateway);\n  } else throw error;\n}","preventionTips":["Install Go binaries before selecting a local wrap-mode gateway","Set CAVEMAN_PROXY_BIN to an absolute path in automation for hermetic resolution","Remember non-local wrap modes skip this requirement — mode choice is the real lever"],"tags":["binary-missing","proxy","local-mode","setup"],"backgroundTag":null,"analyzedSha":"27d5a3981a347890211bb1bf2439e5c821a63bc9","analyzedAt":"2026-08-15T09:26:11.751Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}