{"record":{"id":"55dfeb612ed96225","repo":"google-gemini/gemini-cli","slug":"gemini-sandbox-is-true-but-failed-to-determine-com","errorCode":null,"errorMessage":"GEMINI_SANDBOX is true but failed to determine command for sandbox; install docker or podman or specify command in GEMINI_SANDBOX","messagePattern":"GEMINI_SANDBOX is true but failed to determine command for sandbox; install docker or podman or specify command in GEMINI_SANDBOX","errorType":"exception","errorClass":"FatalSandboxError","httpStatus":null,"severity":"error","filePath":"packages/cli/src/config/sandboxConfig.ts","lineNumber":114,"sourceCode":"      );\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) {\n    return 'docker';\n  } else if (commandExists.sync('podman') && sandbox === true) {\n    return 'podman';\n  }\n\n  // throw an error if user requested sandbox but no command was found\n  if (sandbox === true) {\n    throw new FatalSandboxError(\n      'GEMINI_SANDBOX is true but failed to determine command for sandbox; ' +\n        'install docker or podman or specify command in GEMINI_SANDBOX',\n    );\n  }\n\n  return '';\n  // Note: 'lxc' is intentionally not auto-detected because it requires a\n  // pre-existing, running container managed by the user. Use\n  // GEMINI_SANDBOX=lxc or sandbox: \"lxc\" in settings to enable it.\n}\n\nexport async function loadSandboxConfig(\n  settings: Settings,\n  argv: SandboxCliArgs,\n): Promise<SandboxConfig | undefined> {\n  const sandboxOption = argv.sandbox ?? settings.tools?.sandbox;\n\n  let sandboxValue: boolean | string | null | undefined;","sourceCodeStart":96,"sourceCodeEnd":132,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/packages/cli/src/config/sandboxConfig.ts#L96-L132","documentation":"Thrown by getSandboxCommand() when sandboxing is explicitly enabled (sandbox === true) but no usable backend could be auto-detected. It is a FatalSandboxError (exit code 44). Auto-detection only resolves 'sandbox-exec' on macOS, and 'docker'/'podman' on any OS when sandbox is explicitly true; 'runsc' and 'lxc' are intentionally never auto-detected and must be named explicitly via GEMINI_SANDBOX.","triggerScenarios":"GEMINI_SANDBOX=true (or '1') is set, or settings.tools.sandbox === true / --sandbox passed, AND commandExists.sync('docker') and commandExists.sync('podman') both return false, AND the platform is not macOS with sandbox-exec available. Also triggered when SANDBOX env var is NOT already set (which would short-circuit to '').","commonSituations":"Running on a Linux CI runner or container without Docker/Podman installed; a fresh dev machine where GEMINI_SANDBOX was enabled globally but the container runtime was never installed; copying a config with sandbox:true into an environment lacking the runtime.","solutions":["Install docker or podman on the machine and ensure it is on PATH (verify with `which docker`).","Pin a specific backend by setting GEMINI_SANDBOX=docker (or podman/runsc/lxc/sandbox-exec/windows-native) instead of bare true.","Disable sandboxing if it is not required: remove GEMINI_SANDBOX, set GEMINI_SANDBOX=false, or drop the sandbox key from settings.json.","On macOS, confirm sandbox-exec exists (it ships with the OS) so auto-detection picks it up without needing docker."],"exampleFix":"// before\nGEMINI_SANDBOX=true gemini -p \"hi\"\n// after (pick one)\nGEMINI_SANDBOX=docker gemini -p \"hi\"\n# or uninstall intent: leave GEMINI_SANDBOX unset","handlingStrategy":"validation","validationCode":"import commandExists from 'command-exists';\nimport * as os from 'node:os';\n\nfunction resolveSandboxCommand(explicit?: string): string | null {\n  if (process.env['SANDBOX']) return ''; // already sandboxed\n  const want = (process.env['GEMINI_SANDBOX']?.toLowerCase().trim() || explicit || '').toString();\n  if (!want || want === '0' || want === 'false') return '';\n  if (os.platform() === 'darwin' && commandExists.sync('sandbox-exec')) return 'sandbox-exec';\n  if (commandExists.sync('docker')) return 'docker';\n  if (commandExists.sync('podman')) return 'podman';\n  return null; // will cause FatalSandboxError if want is '1'/'true'\n}\n\nconst cmd = resolveSandboxCommand();\nif (cmd === null && /^(1|true)$/.test((process.env['GEMINI_SANDBOX'] || '').toLowerCase())) {\n  throw new Error('Install docker/podman or set GEMINI_SANDBOX=docker before launch');\n}","typeGuard":"function hasSandboxBackend(): boolean {\n  if (os.platform() === 'darwin' && commandExists.sync('sandbox-exec')) return true;\n  return commandExists.sync('docker') || commandExists.sync('podman');\n}","tryCatchPattern":"try {\n  await loadSandboxConfig(settings, argv);\n} catch (e) {\n  if (e instanceof FatalSandboxError && /failed to determine command/.test(e.message)) {\n    // exit code 44: prompt user to install a backend or disable sandbox\n    console.error('No sandbox backend found. Install docker/podman or unset GEMINI_SANDBOX.');\n  }\n  throw e;\n}","preventionTips":["In Dockerfiles/CI images, install docker or podman (or set GEMINI_SANDBOX to the available one) before enabling sandbox.","Pin GEMINI_SANDBOX to a named backend rather than bare true so failures are explicit.","Document the sandbox backend requirement wherever sandbox:true is set in shared configs."],"tags":["sandbox","configuration","environment","docker","podman"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}