{"record":{"id":"568aa2cbf87f08e0","repo":"google-gemini/gemini-cli","slug":"missing-sandbox-command-sandbox-from-gemini","errorCode":null,"errorMessage":"Missing sandbox command '${sandbox}' (from GEMINI_SANDBOX)","messagePattern":"Missing sandbox command '(.+?)' \\(from GEMINI_SANDBOX\\)","errorType":"exception","errorClass":"FatalSandboxError","httpStatus":null,"severity":"error","filePath":"packages/cli/src/config/sandboxConfig.ts","lineNumber":88,"sourceCode":"        )}`,\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  }\n\n  // look for seatbelt, docker, or podman, in that order\n  // for container-based sandboxing, require sandbox to be enabled explicitly\n  // note: runsc is NOT auto-detected, it must be explicitly specified\n  if (os.platform() === 'darwin' && commandExists.sync('sandbox-exec')) {\n    return 'sandbox-exec';\n  } else if (commandExists.sync('docker') && sandbox === true) {","sourceCodeStart":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/packages/cli/src/config/sandboxConfig.ts#L70-L106","documentation":"Thrown as FatalSandboxError when the chosen sandbox command is valid by name but commandExists.sync(sandbox) returns false — the binary is not on PATH. windows-native is exempt (it is built-in); all other commands must be discoverable as an executable.","triggerScenarios":"GEMINI_SANDBOX=docker (or podman/lxc/sandbox-exec) is set but the corresponding binary is not installed or not on PATH in the current shell.","commonSituations":"Docker/Podman not installed; binary installed but PATH not updated (new install, non-login shell, IDE-launched terminal with a trimmed PATH); container/CI image lacking the runtime.","solutions":["Install the sandbox runtime (docker/podman/lxc/sandbox-exec) and ensure it is on PATH.","Restart the shell/IDE so PATH is refreshed, or source the runtime's profile.","Unset GEMINI_SANDBOX to use auto-detection of whatever runtime is actually present."],"exampleFix":"// before\nexport GEMINI_SANDBOX=podman   # podman not installed\n// after\nsudo apt-get install podman && export GEMINI_SANDBOX=podman","handlingStrategy":"validation","validationCode":"import commandExists from 'command-exists';\nfunction sandboxBinaryPresent(cmd: string): boolean { return cmd === 'windows-native' || commandExists.sync(cmd); }","typeGuard":"function sandboxAvailable(cmd: string): boolean { return cmd === 'windows-native' || commandExists.sync(cmd); }","tryCatchPattern":null,"preventionTips":["Install the chosen runtime and refresh PATH (new shell / re-login).","Prefer unset GEMINI_SANDBOX so auto-detection picks a present runtime."],"tags":["sandbox","config","path","fatal"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}