caveman-proxy ${probe.version} lacks current native_runtime_

Error message

caveman-proxy ${probe.version} lacks current native_runtime_v1 capability; run \`caveman setup --install\`

What it means

Thrown by nativeProxyBinaryRequired() when Caveman runs in 'local' wrap mode: it resolves the caveman-proxy Go binary (via resolveGoBin/CAVEMAN_PROXY_BIN) and probes it with probeVersionedBinary(binary, "native_runtime_v1"). If the installed binary's version does not satisfy the native_runtime_v1 capability, the proxy is too old to host native integrations and the install aborts before touching any agent config.

Source

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

  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 });
    if (out.error) return { binary, launchable: false, version: null, error: boundedHookString(out.error.message, 240) ?? "version_probe_failed" };
    const value = `${out.stdout ?? ""} ${out.stderr ?? ""}`.trim();
    if (out.status !== 0) return { binary, launchable: false, version: value ? value.slice(0, 160) : null, error: `version_probe_exit_${out.status ?? "unknown"}` };
    return { binary, launchable: true, version: value ? value.slice(0, 160) : null, error: null };
  } catch {
    return { binary, launchable: false, version: null, error: "version_probe_failed" };
  }
}

function detectedAgentVersion(agent: AgentProfile): string | null { return nativeHostProbe(agent).version; }

View on GitHub (pinned to 27d5a3981a)

Solutions

Run `caveman setup --install` to rebuild/reinstall caveman-proxy at the expected version
Check `echo $CAVEMAN_PROXY_BIN` and `which caveman-proxy`; unset the override or fix PATH so the fresh binary resolves first
Re-run the native integration command that failed after the install completes
If install fails, verify the Go toolchain is present (the proxy is built from source) and retry `caveman setup --install`

Example fix

# before
$ caveman native install claude
Error: caveman-proxy v0.3.1 lacks current native_runtime_v1 capability; run `caveman setup --install`

# after
$ caveman setup --install
$ caveman native install claude   # succeeds

Defensive patterns

Strategy: validation

Validate before calling

// Before native install, probe the proxy binary the same way the CLI does
import { spawnSync } from "node:child_process";
function proxyHasNativeRuntime(bin: string): boolean {
  const out = spawnSync(bin, ["--capabilities"], { encoding: "utf8", timeout: 3000 });
  return !out.error && `${out.stdout}${out.stderr}`.includes("native_runtime_v1");
}
if (!proxyHasNativeRuntime(process.env.CAVEMAN_PROXY_BIN ?? "caveman-proxy")) {
  spawnSync("caveman", ["setup", "--install"], { stdio: "inherit" });
}

Try / catch

try {
  runNativeInstall();
} catch (e) {
  if (e instanceof Error && /lacks current native_runtime_v1/.test(e.message)) {
    await installThenRetry(); // caveman setup --install, then retry once
  } else throw e;
}

Prevention

Run `caveman setup --install` immediately after upgrading the caveman CLI so the Go binaries stay in sync
Do not pin CAVEMAN_PROXY_BIN to a checkout; let the managed install own the binary location
In automation, probe the proxy capability before invoking integration installs

When it happens

Trigger: Any native agent-integration install path (e.g. `caveman setup`, enabling claude/gemini/opencode/aider/codex/hermes native routing) while wrapMode(gateway) === "local" and the resolved caveman-proxy binary reports a version lacking native_runtime_v1 (old build on PATH, or CAVEMAN_PROXY_BIN pointing at a stale binary).

Common situations: Upgraded the caveman CLI without reinstalling Go binaries; CAVEMAN_PROXY_BIN env var pinned to an old checkout/build; a second caveman install earlier on PATH; partial `caveman setup --install` that failed mid-way.

Related errors

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