JuliusBrussee/caveman · error

caveman-mcp not found; run `caveman setup --install`

Error message

caveman-mcp not found; run `caveman setup --install`

What it means

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.

Source

Thrown at packages/cli/src/index.ts:6005

    writeFileSync(temp, bytes, { mode });
    renameSync(temp, path);
    chmodSync(path, mode);
  } catch (error) {
    try { unlinkSync(temp); } catch { /* no partial */ }
    throw error;
  }
}

function parseJsonFileObject(path: string, bytes: Buffer | null): Record<string, unknown> {
  if (!bytes || bytes.length === 0) return {};
  const parsed = JSON.parse(bytes.toString("utf8"));
  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`${path} is not a JSON object`);
  return parsed as Record<string, unknown>;
}

function nativeMcpBinaryRequired(): string {
  const compatible = probeMcpBinary();
  if (!compatible) throw new Error("caveman-mcp not found; run `caveman setup --install`");
  if (!compatible.probe.current) throw new Error(`caveman-mcp ${compatible.probe.version} lacks current mcp_recovery capability; run \`caveman setup --install\``);
  return compatible.binary;
}

function nativeProxyBinaryRequired(gw: string): void {
  if (wrapMode(gw) !== "local") return;
  const binary = resolveGoBin("caveman-proxy", "CAVEMAN_PROXY_BIN");
  if (!binary) throw new Error("caveman-proxy not found; run `caveman setup --install`");
  const probe = probeVersionedBinary(binary, "native_runtime_v1");
  if (!probe.current) throw new Error(`caveman-proxy ${probe.version} lacks current native_runtime_v1 capability; run \`caveman setup --install\``);
}

function nativeHostProbe(agent: AgentProfile): { binary: string | null; launchable: boolean; version: string | null; error: string | null } {
  const binary = which(binOf(agent));
  if (!binary) return { binary: null, launchable: false, version: null, error: "binary_not_found" };
  try {
    const invocation = portableInvocation(binary, ["--version"]);
    const out = spawnSync(invocation.command, invocation.args, { encoding: "utf8", timeout: 3000 });

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Run `caveman setup --install` to build/install the Go binaries
2. Ensure the Go bin directory (go env GOBIN or ~/go/bin) is on PATH
3. Point the environment override at an existing caveman-mcp binary if installed elsewhere
4. Verify with `which caveman-mcp` and `caveman-mcp --version`

Example fix

# before
caveman setup --agent-native claude  # Error: caveman-mcp not found

# after
caveman setup --install
caveman setup --agent-native claude

import { which } from "caveman";
if (!which("caveman-mcp")) {
  throw new Error("caveman-mcp missing; run `caveman setup --install` first");
}

try {
  nativeMcpBinaryRequired();
} catch (error) {
  if (/caveman-mcp not found/.test((error as Error).message)) {
    throw new Error("precondition failed: run `caveman setup --install` and re-run this step", { cause: error });
  }
  throw error;  // version-capability failures need a binary upgrade, same command
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• caveman-proxy not found; run `caveman setup --install`
• registry output has no capabilities
• cave_transform_registry_unavailable: run caveman setup or se
• ${key} is required
• filters must be an object

AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15). Data as JSON: /api/errors/fa2891182591829a. Report an issue: GitHub.