JuliusBrussee/caveman · error

cave_sandbox_os_network_isolation_unavailable

Error message

cave_sandbox_os_network_isolation_unavailable

What it means

networkIsolatedNode returns an OS-level network-isolation wrapper command (sandbox-exec on macOS, unshare --net on Linux) and throws this error on any other platform. The sandbox needs kernel-level network containment for tool workers; Windows and other non-darwin/linux platforms have no supported wrapper, so the request fails closed rather than running unsandboxed.

Source

Thrown at packages/agent/src/sandbox-network.ts:65

        ...nodeArgs,
      ],
    };
  }
  if (process.platform === "linux") {
    return {
      command: "/usr/bin/unshare",
      args: [
        "--user",
        "--map-root-user",
        "--net",
        "--",
        process.execPath,
        "--no-addons",
        ...nodeArgs,
      ],
    };
  }
  throw new Error("cave_sandbox_os_network_isolation_unavailable");
}

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Run sandboxed builds on Linux or macOS; on Windows use WSL so Node reports platform "linux".
2. Verify sandbox readiness with the doctor CLI before attempting the run — missing sandbox support is reported there.
3. If your policy allows it, use a sandbox mode that does not require OS network isolation rather than weakening the required policy silently.

Example fix

// before
const plan = await compile(agent, { sandbox: "required" }); // on Windows

// after
// run under WSL/Linux, or gate on platform:
if (process.platform !== "darwin" && process.platform !== "linux") {
  throw new Error("OS network isolation unsupported here; use WSL or Linux");
}

function osNetworkIsolationAvailable(): boolean {
  return process.platform === "darwin" || process.platform === "linux";
}
if (!osNetworkIsolationAvailable()) {
  throw new Error(`OS network isolation unavailable on ${process.platform}; use Linux, macOS, or WSL`);
}

try {
  await buildWithRequiredSandbox(agent);
} catch (error) {
  if (error instanceof Error && error.message === "cave_sandbox_os_network_isolation_unavailable") {
    // fail closed by design: switch environment, do not drop the sandbox policy
  } else throw error;
}

When it happens

Trigger: Requesting an OS-network-isolated sandboxed run (required-sandbox policy with network isolation) on Windows or any platform where process.platform is neither "darwin" nor "linux".

Common situations: Developing on Windows (including WSL-confused setups where the host Node reports win32); CI runners on unsupported platforms; expecting the in-process installNetworkDeny() shim to suffice where the OS wrapper is required.

Related errors

• probe returned false
• registration failed: HTTP ${response.status}
• cave_sandbox_conformance_failed
• caveman build: config must use strict lock and required sand
• cave_live_eval_sandbox_profile_missing

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