google-gemini/gemini-cli · error · FatalSandboxError

runsc (gVisor) requires Docker. Install Docker, or use sandb

Error message

runsc (gVisor) requires Docker. Install Docker, or use sandbox: 'docker'.

What it means

Thrown as FatalSandboxError when sandbox is 'runsc' and commandExists.sync('docker') is false. gVisor's runsc is used as a Docker runtime (--runtime=runsc), so even on Linux both the runsc binary and Docker must be present; the error steers the user to install Docker or fall back to plain docker sandboxing.

Source

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

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

  // throw an error if user requested sandbox but no command was found

View on GitHub (pinned to 5024443c72)

Solutions

Install Docker (engine + CLI) and ensure 'docker' is on PATH.
If Docker is unavailable, switch to GEMINI_SANDBOX=podman or remove the sandbox setting.
Verify with 'docker info' that the daemon is reachable before retrying.

Example fix

// before
export GEMINI_SANDBOX=runsc   # no docker installed
// after
sudo apt-get install docker.io && export GEMINI_SANDBOX=runsc

Defensive patterns

Strategy: validation

Validate before calling

import commandExists from 'command-exists';
function runscReady(): boolean { return os.platform() === 'linux' && commandExists.sync('runsc') && commandExists.sync('docker'); }

Type guard

function runscReady(): boolean { return commandExists.sync('docker') && commandExists.sync('runsc'); }

Prevention

Install Docker when selecting runsc, or switch to GEMINI_SANDBOX=docker.
Verify 'docker info' works before relying on runsc.

When it happens

Trigger: GEMINI_SANDBOX=runsc on Linux where runsc is installed but Docker is not (or docker is not on PATH).

Common situations: runsc installed for testing without a Docker engine; minimal VM/container that has runsc but not dockerd; Docker binary renamed or not on PATH.

Related errors

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