google-gemini/gemini-cli · error · FatalSandboxError

Windows native sandboxing is only supported on Windows

Error message

Windows native sandboxing is only supported on Windows

What it means

Thrown as FatalSandboxError when sandbox is 'windows-native' but os.platform() is not 'win32'. The windows-native sandbox relies on Windows-specific job objects/APIs and cannot run on macOS/Linux, so it is rejected up front.

Source

Thrown at packages/cli/src/config/sandboxConfig.ts:81

  }

  if (typeof sandbox === 'string' && sandbox) {
    if (!isSandboxCommand(sandbox)) {
      throw new FatalSandboxError(
        `Invalid sandbox command '${sandbox}'. Must be one of ${VALID_SANDBOX_COMMANDS.join(
          ', ',
        )}`,
      );
    }
    // runsc (gVisor) is only supported on Linux
    if (sandbox === 'runsc' && os.platform() !== 'linux') {
      throw new FatalSandboxError(
        'gVisor (runsc) sandboxing is only supported on Linux',
      );
    }
    // windows-native is only supported on Windows
    if (sandbox === 'windows-native' && os.platform() !== 'win32') {
      throw new FatalSandboxError(
        'Windows native sandboxing is only supported on Windows',
      );
    }

    // confirm that specified command exists (unless it's built-in)
    if (sandbox !== 'windows-native' && !commandExists.sync(sandbox)) {
      throw new FatalSandboxError(
        `Missing sandbox command '${sandbox}' (from GEMINI_SANDBOX)`,
      );
    }
    // runsc uses Docker with --runtime=runsc; both must be available (prioritize runsc when explicitly chosen)
    if (sandbox === 'runsc' && !commandExists.sync('docker')) {
      throw new FatalSandboxError(
        "runsc (gVisor) requires Docker. Install Docker, or use sandbox: 'docker'.",
      );
    }
    return sandbox;
  }

View on GitHub (pinned to 5024443c72)

Solutions

1. Only set windows-native on Windows; on macOS use sandbox-exec, on Linux use docker/runsc/podman.
2. Gate the sandbox export by OS in your environment setup.
3. Unset GEMINI_SANDBOX to let the CLI auto-detect a suitable sandbox.

Example fix

// before
export GEMINI_SANDBOX=windows-native
// after
if [ "$OS" = 'Windows_NT' ]; then export GEMINI_SANDBOX=windows-native; fi

function canUseWindowsNative(): boolean { return os.platform() === 'win32'; }

function windowsNativeSupported(): boolean { return os.platform() === 'win32'; }

When it happens

Trigger: GEMINI_SANDBOX=windows-native or sandbox='windows-native' on macOS or Linux.

Common situations: Cross-platform env/dotfiles that hardcode windows-native; copy-pasted config from a Windows guide onto another OS.

Related errors

• gVisor (runsc) sandboxing is only supported on Linux
• Invalid sandbox command '${sandbox}'. Must be one of ${VALID
• Missing sandbox command '${sandbox}' (from GEMINI_SANDBOX)
• runsc (gVisor) requires Docker. Install Docker, or use sandb
• Workspace path ${resolvedPath} is outside the allowed root d

AI-assisted analysis of google-gemini/gemini-cli@5024443c72 (2026-08-12). Data as JSON: /api/errors/7e74f2d3c259603b. Report an issue: GitHub.