google-gemini/gemini-cli · error · FatalSandboxError

GEMINI_SANDBOX is true but failed to determine command for s

Error message

GEMINI_SANDBOX is true but failed to determine command for sandbox; install docker or podman or specify command in GEMINI_SANDBOX

What it means

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.

Source

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

      );
    }
    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) {
    return 'docker';
  } else if (commandExists.sync('podman') && sandbox === true) {
    return 'podman';
  }

  // throw an error if user requested sandbox but no command was found
  if (sandbox === true) {
    throw new FatalSandboxError(
      'GEMINI_SANDBOX is true but failed to determine command for sandbox; ' +
        'install docker or podman or specify command in GEMINI_SANDBOX',
    );
  }

  return '';
  // Note: 'lxc' is intentionally not auto-detected because it requires a
  // pre-existing, running container managed by the user. Use
  // GEMINI_SANDBOX=lxc or sandbox: "lxc" in settings to enable it.
}

export async function loadSandboxConfig(
  settings: Settings,
  argv: SandboxCliArgs,
): Promise<SandboxConfig | undefined> {
  const sandboxOption = argv.sandbox ?? settings.tools?.sandbox;

  let sandboxValue: boolean | string | null | undefined;

View on GitHub (pinned to 5024443c72)

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.

Example fix

// before
GEMINI_SANDBOX=true gemini -p "hi"
// after (pick one)
GEMINI_SANDBOX=docker gemini -p "hi"
# or uninstall intent: leave GEMINI_SANDBOX unset

Defensive patterns

Strategy: validation

Validate before calling

import commandExists from 'command-exists';
import * as os from 'node:os';

function resolveSandboxCommand(explicit?: string): string | null {
  if (process.env['SANDBOX']) return ''; // already sandboxed
  const want = (process.env['GEMINI_SANDBOX']?.toLowerCase().trim() || explicit || '').toString();
  if (!want || want === '0' || want === 'false') return '';
  if (os.platform() === 'darwin' && commandExists.sync('sandbox-exec')) return 'sandbox-exec';
  if (commandExists.sync('docker')) return 'docker';
  if (commandExists.sync('podman')) return 'podman';
  return null; // will cause FatalSandboxError if want is '1'/'true'
}

const cmd = resolveSandboxCommand();
if (cmd === null && /^(1|true)$/.test((process.env['GEMINI_SANDBOX'] || '').toLowerCase())) {
  throw new Error('Install docker/podman or set GEMINI_SANDBOX=docker before launch');
}

Type guard

function hasSandboxBackend(): boolean {
  if (os.platform() === 'darwin' && commandExists.sync('sandbox-exec')) return true;
  return commandExists.sync('docker') || commandExists.sync('podman');
}

Try / catch

try {
  await loadSandboxConfig(settings, argv);
} catch (e) {
  if (e instanceof FatalSandboxError && /failed to determine command/.test(e.message)) {
    // exit code 44: prompt user to install a backend or disable sandbox
    console.error('No sandbox backend found. Install docker/podman or unset GEMINI_SANDBOX.');
  }
  throw e;
}

Prevention

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.

When it happens

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

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

Related errors

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