{"record":{"id":"e14ed218cc16f13a","repo":"google-gemini/gemini-cli","slug":"invalid-sandbox-command-sandbox-must-be-one","errorCode":null,"errorMessage":"Invalid sandbox command '${sandbox}'. Must be one of ${VALID_SANDBOX_COMMANDS.join(', ')}","messagePattern":"Invalid sandbox command '(.+?)'\\. Must be one of (.+?)","errorType":"exception","errorClass":"FatalSandboxError","httpStatus":null,"severity":"error","filePath":"packages/cli/src/config/sandboxConfig.ts","lineNumber":67,"sourceCode":"  }\n\n  // note environment variable takes precedence over argument (from command line or settings)\n  const environmentConfiguredSandbox =\n    process.env['GEMINI_SANDBOX']?.toLowerCase().trim() ?? '';\n  sandbox =\n    environmentConfiguredSandbox?.length > 0\n      ? environmentConfiguredSandbox\n      : sandbox;\n  if (sandbox === '1' || sandbox === 'true') sandbox = true;\n  else if (sandbox === '0' || sandbox === 'false' || !sandbox) sandbox = false;\n\n  if (sandbox === false) {\n    return '';\n  }\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","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/packages/cli/src/config/sandboxConfig.ts#L49-L85","documentation":"Thrown as FatalSandboxError by getSandboxCommand when the configured sandbox value is a non-empty string that is not in VALID_SANDBOX_COMMANDS (docker, podman, sandbox-exec, runsc, lxc, windows-native). The value comes from GEMINI_SANDBOX env var (which takes precedence) or the sandbox CLI/settings argument.","triggerScenarios":"Setting GEMINI_SANDBOX=firejail (or any unrecognized command), or passing --sandbox=nsjail; the string is non-empty and fails isSandboxCommand().","commonSituations":"Typo in the sandbox name; using a sandbox tool the CLI does not support; stale docs suggesting a command removed from the allow-list.","solutions":["Set GEMINI_SANDBOX (or the sandbox flag) to one of: docker, podman, sandbox-exec, runsc, lxc, windows-native.","Leave GEMINI_SANDBOX unset to use auto-detection (seatbelt/docker/podman).","Disable sandboxing with GEMINI_SANDBOX=false or 0 if you do not need it."],"exampleFix":"// before\nexport GEMINI_SANDBOX=firejail\n// after\nexport GEMINI_SANDBOX=docker","handlingStrategy":"validation","validationCode":"const VALID = ['docker','podman','sandbox-exec','runsc','lxc','windows-native'];\nfunction isValidSandbox(v: string): boolean { return VALID.includes(v); }","typeGuard":"function isSandboxCommand(v: string): v is 'docker'|'podman'|'sandbox-exec'|'runsc'|'lxc'|'windows-native' { return ['docker','podman','sandbox-exec','runsc','lxc','windows-native'].includes(v); }","tryCatchPattern":null,"preventionTips":["Set GEMINI_SANDBOX only to a supported command, or leave it unset for auto-detect.","Validate the value in your environment bootstrap before launching the CLI."],"tags":["sandbox","config","validation","fatal"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}