{"record":{"id":"7e74f2d3c259603b","repo":"google-gemini/gemini-cli","slug":"windows-native-sandboxing-is-only-supported-on-win","errorCode":null,"errorMessage":"Windows native sandboxing is only supported on Windows","messagePattern":"Windows native sandboxing is only supported on Windows","errorType":"exception","errorClass":"FatalSandboxError","httpStatus":null,"severity":"error","filePath":"packages/cli/src/config/sandboxConfig.ts","lineNumber":81,"sourceCode":"  }\n\n  if (typeof sandbox === 'string' && sandbox) {\n    if (!isSandboxCommand(sandbox)) {\n      throw new FatalSandboxError(\n        `Invalid sandbox command '${sandbox}'. Must be one of ${VALID_SANDBOX_COMMANDS.join(\n          ', ',\n        )}`,\n      );\n    }\n    // runsc (gVisor) is only supported on Linux\n    if (sandbox === 'runsc' && os.platform() !== 'linux') {\n      throw new FatalSandboxError(\n        'gVisor (runsc) sandboxing is only supported on Linux',\n      );\n    }\n    // windows-native is only supported on Windows\n    if (sandbox === 'windows-native' && os.platform() !== 'win32') {\n      throw new FatalSandboxError(\n        'Windows native sandboxing is only supported on Windows',\n      );\n    }\n\n    // confirm that specified command exists (unless it's built-in)\n    if (sandbox !== 'windows-native' && !commandExists.sync(sandbox)) {\n      throw new FatalSandboxError(\n        `Missing sandbox command '${sandbox}' (from GEMINI_SANDBOX)`,\n      );\n    }\n    // runsc uses Docker with --runtime=runsc; both must be available (prioritize runsc when explicitly chosen)\n    if (sandbox === 'runsc' && !commandExists.sync('docker')) {\n      throw new FatalSandboxError(\n        \"runsc (gVisor) requires Docker. Install Docker, or use sandbox: 'docker'.\",\n      );\n    }\n    return sandbox;\n  }","sourceCodeStart":63,"sourceCodeEnd":99,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/packages/cli/src/config/sandboxConfig.ts#L63-L99","documentation":"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.","triggerScenarios":"GEMINI_SANDBOX=windows-native or sandbox='windows-native' on macOS or Linux.","commonSituations":"Cross-platform env/dotfiles that hardcode windows-native; copy-pasted config from a Windows guide onto another OS.","solutions":["Only set windows-native on Windows; on macOS use sandbox-exec, on Linux use docker/runsc/podman.","Gate the sandbox export by OS in your environment setup.","Unset GEMINI_SANDBOX to let the CLI auto-detect a suitable sandbox."],"exampleFix":"// before\nexport GEMINI_SANDBOX=windows-native\n// after\nif [ \"$OS\" = 'Windows_NT' ]; then export GEMINI_SANDBOX=windows-native; fi","handlingStrategy":"validation","validationCode":"function canUseWindowsNative(): boolean { return os.platform() === 'win32'; }","typeGuard":"function windowsNativeSupported(): boolean { return os.platform() === 'win32'; }","tryCatchPattern":null,"preventionTips":["Only set windows-native on Windows.","Use platform-conditional sandbox configuration in cross-platform setups."],"tags":["sandbox","platform","config","fatal"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}