caveman-proxy lacks current native_runtime_v1 capability…

Error message

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

What it means

After locating the `caveman-proxy` binary, the CLI probes it with `probeVersionedBinary(binary, "native_runtime_v1")`. If the binary's reported version does not support the current `native_runtime_v1` capability, it is stale relative to the CLI and is refused to avoid protocol mismatches. Reinstall via `caveman setup --install` to get a matching binary.

Solutions

Run `caveman setup --install` to replace caveman-proxy with a current build
Remove the outdated binary and re-run setup so the fresh one is fetched
Update the pinned CAVEMAN_PROXY_BIN path to the newly installed binary
Run `caveman doctor` to confirm the probe reports current before retrying

Example fix

// before: pinned old build
export CAVEMAN_PROXY_BIN=~/tools/caveman-proxy-0.8.1
// after
$ caveman setup --install
unset CAVEMAN_PROXY_BIN  # let resolveGoBin pick the current install

Defensive patterns

Strategy: validation

Validate before calling

const probe = probeVersionedBinary(proxyPath, 'native_runtime_v1');
if (!probe.current) {
  console.warn(`caveman-proxy ${probe.version} outdated — run: caveman setup --install`);
}

Try / catch

try {
  await startProxy();
} catch (e) {
  if (String(e.message).includes('lacks current native_runtime_v1 capability')) {
    await exec('caveman setup --install');
    return startProxy();
  }
  throw e;
}

Prevention

Upgrade binaries and CLI together; never pin CAVEMAN_PROXY_BIN to an old build
Re-run `caveman setup --install` after npm upgrades
Add a version check (`caveman doctor`) to CI pipelines
Avoid manually copying caveman-proxy binaries between machines

When it happens

Trigger: Calling `nativeProxyBinaryRequired(gw)` with `wrapMode(gw) === "local"` where caveman-proxy exists and is found, but `probeVersionedBinary(binary, "native_runtime_v1").current` is false — i.e. the binary predates the current native runtime protocol.

Common situations: Upgrading the CLI npm package without re-running setup, leaving an older caveman-proxy; manually copying an old binary into the bin directory; pinning CAVEMAN_PROXY_BIN to a project-local outdated build.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20). Data as JSON: /api/errors/044be593f985d260. Report an issue: GitHub.

Appendix: source

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

  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 3ee70a1026)