google-gemini/gemini-cli · error · FatalSandboxError

Invalid sandbox command '${sandbox}'. Must be one of ${VALID

Error message

Invalid sandbox command '${sandbox}'. Must be one of ${VALID_SANDBOX_COMMANDS.join(', ')}

What it means

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.

Source

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

  }

  // note environment variable takes precedence over argument (from command line or settings)
  const environmentConfiguredSandbox =
    process.env['GEMINI_SANDBOX']?.toLowerCase().trim() ?? '';
  sandbox =
    environmentConfiguredSandbox?.length > 0
      ? environmentConfiguredSandbox
      : sandbox;
  if (sandbox === '1' || sandbox === 'true') sandbox = true;
  else if (sandbox === '0' || sandbox === 'false' || !sandbox) sandbox = false;

  if (sandbox === false) {
    return '';
  }

  if (typeof sandbox === 'string' && sandbox) {
    if (!isSandboxCommand(sandbox)) {
      throw new FatalSandboxError(
        `Invalid sandbox command '${sandbox}'. Must be one of ${VALID_SANDBOX_COMMANDS.join(
          ', ',
        )}`,
      );
    }
    // 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',
      );
    }

View on GitHub (pinned to 5024443c72)

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.

Example fix

// before
export GEMINI_SANDBOX=firejail
// after
export GEMINI_SANDBOX=docker

Defensive patterns

Strategy: validation

Validate before calling

const VALID = ['docker','podman','sandbox-exec','runsc','lxc','windows-native'];
function isValidSandbox(v: string): boolean { return VALID.includes(v); }

Type guard

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); }

Prevention

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.

When it happens

Trigger: Setting GEMINI_SANDBOX=firejail (or any unrecognized command), or passing --sandbox=nsjail; the string is non-empty and fails isSandboxCommand().

Common situations: Typo in the sandbox name; using a sandbox tool the CLI does not support; stale docs suggesting a command removed from the allow-list.

Related errors

AI-assisted analysis of google-gemini/gemini-cli@5024443c72 (2026-08-12). Data as JSON: /api/errors/e14ed218cc16f13a. Report an issue: GitHub.