google-gemini/gemini-cli · error · FatalSandboxError

Sandbox image '${image}' is missing or could not be pulled.

Error message

Sandbox image '${image}' is missing or could not be pulled. ${remedy}

What it means

Thrown after ensureSandboxImageIsPresent returns false, meaning the configured sandbox container image is neither present locally nor pullable from a registry. The remedy string differs based on whether the image is the local dev image (LOCAL_DEV_SANDBOX_IMAGE_NAME) or an external one, guiding the user toward building locally or diagnosing network/registry issues.

Source

Thrown at packages/cli/src/utils/sandbox.ts:376

          `cd ${gcRoot} && node scripts/build_sandbox.js -s ${buildArgs}`,
          {
            stdio: 'inherit',
            env: {
              ...process.env,
              GEMINI_SANDBOX: command, // in case sandbox is enabled via flags (see config.ts under cli package)
            },
          },
        );
      }
    }

    // stop if image is missing
    if (!(await ensureSandboxImageIsPresent(command, image, cliConfig))) {
      const remedy =
        image === LOCAL_DEV_SANDBOX_IMAGE_NAME
          ? 'Try running `npm run build:all` or `npm run build:sandbox` under the gemini-cli repo to build it locally, or check the image name and your network connection.'
          : 'Please check the image name, your network connection, or notify gemini-cli-dev@google.com if the issue persists.';
      throw new FatalSandboxError(
        `Sandbox image '${image}' is missing or could not be pulled. ${remedy}`,
      );
    }

    // use interactive mode and auto-remove container on exit
    // run init binary inside container to forward signals & reap zombies
    const args = ['run', '-i', '--rm', '--init', '--workdir', containerWorkdir];

    // explicitly clear the entrypoint to prevent the container's default
    // entrypoint from interfering with the CLI's spawn command.
    args.push('--entrypoint', '');

    // add runsc runtime if using runsc
    if (config.command === 'runsc') {
      args.push('--runtime=runsc');
    }

    // add custom flags from SANDBOX_FLAGS

View on GitHub (pinned to 5024443c72)

Solutions

  1. For the local dev image: run `npm run build:all` or `npm run build:sandbox` in the gemini-cli repo to build it locally.
  2. For an external image: verify the image name and tag in your sandbox config, and confirm `docker pull <image>` (or podman) succeeds manually.
  3. Check network connectivity / proxy settings for the container registry, and ensure the daemon is running (`docker info`).

Example fix

// before: image missing, no build done
// config.image = 'gemini-sandbox:dev'  (LOCAL_DEV_SANDBOX_IMAGE_NAME)

// after: build it locally first
// npm run build:sandbox   # in gemini-cli repo
// gemini --sandbox
Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight: ensure the image is present or buildable before starting the sandbox.
const { execSync } = require('child_process');
const image = config.image;
try {
  execSync(`docker image inspect ${image}`, {stdio:'ignore'});
} catch {
  if (image === LOCAL_DEV_SANDBOX_IMAGE_NAME) {
    execSync('npm run build:sandbox', {cwd: geminiRepoRoot, stdio:'inherit'});
  } else {
    execSync(`docker pull ${image}`, {stdio:'inherit'});
  }
}

Try / catch

try {
  await startSandbox(config);
} catch (e) {
  if (e instanceof FatalSandboxError && /missing or could not be pulled/.test(e.message)) {
    // build/pull then retry once, else surface a user-facing message
  } else throw e;
}

Prevention

When it happens

Trigger: ensureSandboxImageIsPresent returns false: the image is absent, and either it is the local dev image (which cannot be pulled and must be built) or pullImage failed/registry unreachable. See sandbox.ts:1248-1283 for the decision logic.

Common situations: First run on a fresh machine without the dev image built. Corporate proxy/firewall blocking the container registry. Typo in the configured image name. Docker/podman daemon not running so both inspect and pull fail. Offline environment with no cached image.

Related errors

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