JuliusBrussee/caveman · error · Error

probe returned false

Error message

probe returned false

What it means

Inside doctor's sandbox check, verifySandboxConformance() (exported from runtime.ts:818) runs a containment probe against the tool sandbox and returned false rather than throwing — meaning the probe completed but the sandbox failed to contain it. Doctor wraps this in its own throw so the check is recorded as a failure with the platform-specific fix text (WSL2 on Windows, supported runtime/OS otherwise).

Source

Thrown at packages/agent/src/cli.ts:152

async function doctor(args: string[]): Promise<void> {
  if (args.some((value) => value !== "--json")) {
    throw new Error("usage: caveman-agent doctor [--json]");
  }
  const json = args.includes("--json");
  const root = process.cwd();
  const checks: DoctorCheck[] = [];
  const node = process.versions.node;
  checks.push(compareNodeVersion(node, "22.19.0") >= 0
    ? { id: "node", status: "pass", detail: `Node ${node}` }
    : {
      id: "node",
      status: "fail",
      detail: `Node ${node}; framework requires >=22.19.0`,
      fix: "install Node 22.19 or newer",
    });

  try {
    if (!await verifySandboxConformance()) throw new Error("probe returned false");
    checks.push({ id: "sandbox", status: "pass", detail: "tool sandbox containment probe passed" });
  } catch (error) {
    checks.push({
      id: "sandbox",
      status: "fail",
      detail: `tool sandbox containment unavailable: ${safeDiagnostic(error)}`,
      fix: process.platform === "win32"
        ? "run sandbox-required agents in WSL2; native Windows host-mode agents work, but required containment stays fail-closed"
        : "use supported Node runtime and OS; do not run production tools with sandbox fixture",
    });
  }

  // Missing engine and missing runtime are WARN, not FAIL: without them runs
  // still reach a real model response in observe-only mode (no transform or
  // gateway telemetry; provider usage and local context estimates remain). Only conditions that make even an
  // observe-only run untrustworthy fail this command.
  try {
    const registry = await loadTransformRegistry();

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Apply the fix doctor prints: on Windows use WSL2 for sandbox-required agents; elsewhere ensure a supported Node/OS combo and never run production tools with the sandbox fixture.
2. On Linux CI, enable unprivileged user namespaces and the seccomp surface the sandbox needs (or run the container with the runtime's recommended flags).
3. Re-run `caveman-agent doctor` to confirm the sandbox check flips to pass before attempting builds (build itself hard-fails with cave_sandbox_conformance_failed otherwise).

Example fix

# before: hardened runner, userns disabled
sysctl kernel.unprivileged_userns_clone=0

# after: enable unprivileged userns, re-probe
sudo sysctl kernel.unprivileged_userns_clone=1
caveman-agent doctor

import { verifySandboxConformance } from "@caveman/agent";
const sandboxOk = await verifySandboxConformance();
if (!sandboxOk) {
  console.error("sandbox containment failed; fix host (userns/seccomp/WSL2) before proceeding");
  process.exit(1);
}

try {
  await verifySandboxConformance();
} catch (error) {
  // doctor already wraps this into a structured check; in your own code treat
  // false/throw as an environment blocker, not a transient failure
  reportEnvironmentBlocker("sandbox", error);
}

When it happens

Trigger: Running `caveman-agent doctor` on a host where the tool sandbox fails containment: unsupported kernel/seccomp, sandbox fixture mode active in production, containers missing the required syscall surface (e.g. restricted gVisor/Firecracker microVMs), or macOS/Windows without the required sandbox facility.

Common situations: First-run diagnostics on a new dev machine or CI container; running inside `docker run` without adequate privileges; production deployment on a hardened runner where unprivileged user namespaces are disabled (sysctl kernel.unprivileged_userns_clone=0).

Related errors

• cave_sandbox_conformance_failed
• cave_live_eval_sandbox_profile_escapes_root
• caveman-code: path escapes the workspace: ${candidate}
• cave_host_sandbox_nested_under_required
• cave_sandbox_credential_env_not_allowlisted

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