google-gemini/gemini-cli · error · FatalSandboxError

Missing sandbox command '${sandbox}' (from GEMINI_SANDBOX)

Error message

Missing sandbox command '${sandbox}' (from GEMINI_SANDBOX)

What it means

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.

Source

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

        )}`,
      );
    }
    // 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;
  }

  // look for seatbelt, docker, or podman, in that order
  // for container-based sandboxing, require sandbox to be enabled explicitly
  // note: runsc is NOT auto-detected, it must be explicitly specified
  if (os.platform() === 'darwin' && commandExists.sync('sandbox-exec')) {
    return 'sandbox-exec';
  } else if (commandExists.sync('docker') && sandbox === true) {

View on GitHub (pinned to 5024443c72)

Solutions

1. Install the sandbox runtime (docker/podman/lxc/sandbox-exec) and ensure it is on PATH.
2. Restart the shell/IDE so PATH is refreshed, or source the runtime's profile.
3. Unset GEMINI_SANDBOX to use auto-detection of whatever runtime is actually present.

Example fix

// before
export GEMINI_SANDBOX=podman   # podman not installed
// after
sudo apt-get install podman && export GEMINI_SANDBOX=podman

import commandExists from 'command-exists';
function sandboxBinaryPresent(cmd: string): boolean { return cmd === 'windows-native' || commandExists.sync(cmd); }

function sandboxAvailable(cmd: string): boolean { return cmd === 'windows-native' || commandExists.sync(cmd); }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Invalid sandbox command '${sandbox}'. Must be one of ${VALID
• gVisor (runsc) sandboxing is only supported on Linux
• Windows native sandboxing is only supported on Windows
• 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/568aa2cbf87f08e0. Report an issue: GitHub.