{"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":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/index.ts","lineNumber":6994,"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":6976,"sourceCodeEnd":7012,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/cli/src/index.ts#L6976-L7012","documentation":"`nativeProxyBinaryRequired()` resolves the `caveman-proxy` binary (via `resolveGoBin` honoring `CAVEMAN_PROXY_BIN`) when running in local wrap mode. If the binary cannot be found on disk or PATH, the CLI cannot route local traffic through the proxy and throws this error directing the user to install it with `caveman setup --install`.","triggerScenarios":"Running a CLI command that routes through a local gateway (`wrapMode(gw) === \"local\"`) when `resolveGoBin(\"caveman-proxy\", \"CAVEMAN_PROXY_BIN\")` returns null — i.e. caveman-proxy is absent from the expected install location, PATH, and the CAVEMAN_PROXY_BIN override is unset or points nowhere.","commonSituations":"Fresh CLI install where `caveman setup --install` was never run; CI/container images with only the npm package installed but no Go binaries; CAVEMAN_PROXY_BIN pointing at a deleted/renamed path; setup interrupted before the proxy binary was downloaded.","solutions":["Run `caveman setup --install` to install caveman-proxy","Set CAVEMAN_PROXY_BIN to the absolute path of an existing caveman-proxy binary","Verify the binary exists: `which caveman-proxy` or check ~/.caveman/bin","Switch wrap mode away from `local` if the native proxy is intentionally unavailable"],"exampleFix":"// before: env var points at removed binary\nexport CAVEMAN_PROXY_BIN=/opt/old/caveman-proxy  # gone after cleanup\n// after\n$ caveman setup --install   # restores the binary\n// or\nexport CAVEMAN_PROXY_BIN=$HOME/.caveman/bin/caveman-proxy","handlingStrategy":"validation","validationCode":"// Pre-check binary availability before calling:\nconst bin = process.env.CAVEMAN_PROXY_BIN || 'caveman-proxy';\nif (!fs.existsSync(bin) && !which('caveman-proxy')) {\n  throw new Error('caveman-proxy missing — run: caveman setup --install');\n}","typeGuard":null,"tryCatchPattern":"try {\n  await startProxy();\n} catch (e) {\n  if (String(e.message).includes('caveman-proxy not found')) {\n    await exec('caveman setup --install');\n    return startProxy();\n  }\n  throw e;\n}","preventionTips":["Run `caveman setup --install` as part of environment bootstrap (Dockerfile, CI setup step)","Verify CAVEMAN_PROXY_BIN points at an existing file before use","Check `which caveman-proxy` after any system cleanup that touches ~/.caveman/bin","Use `caveman doctor` as a preflight in scripts"],"tags":["cli","missing-binary","setup","proxy"],"backgroundTag":"file-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"}