{"record":{"id":"5d7edefc10d9b68e","repo":"google-gemini/gemini-cli","slug":"sandbox-image-image-is-missing-or-could-not-b","errorCode":null,"errorMessage":"Sandbox image '${image}' is missing or could not be pulled. ${remedy}","messagePattern":"Sandbox image '(.+?)' is missing or could not be pulled\\. (.+?)","errorType":"exception","errorClass":"FatalSandboxError","httpStatus":null,"severity":"error","filePath":"packages/cli/src/utils/sandbox.ts","lineNumber":376,"sourceCode":"          `cd ${gcRoot} && node scripts/build_sandbox.js -s ${buildArgs}`,\n          {\n            stdio: 'inherit',\n            env: {\n              ...process.env,\n              GEMINI_SANDBOX: command, // in case sandbox is enabled via flags (see config.ts under cli package)\n            },\n          },\n        );\n      }\n    }\n\n    // stop if image is missing\n    if (!(await ensureSandboxImageIsPresent(command, image, cliConfig))) {\n      const remedy =\n        image === LOCAL_DEV_SANDBOX_IMAGE_NAME\n          ? '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.'\n          : 'Please check the image name, your network connection, or notify gemini-cli-dev@google.com if the issue persists.';\n      throw new FatalSandboxError(\n        `Sandbox image '${image}' is missing or could not be pulled. ${remedy}`,\n      );\n    }\n\n    // use interactive mode and auto-remove container on exit\n    // run init binary inside container to forward signals & reap zombies\n    const args = ['run', '-i', '--rm', '--init', '--workdir', containerWorkdir];\n\n    // explicitly clear the entrypoint to prevent the container's default\n    // entrypoint from interfering with the CLI's spawn command.\n    args.push('--entrypoint', '');\n\n    // add runsc runtime if using runsc\n    if (config.command === 'runsc') {\n      args.push('--runtime=runsc');\n    }\n\n    // add custom flags from SANDBOX_FLAGS","sourceCodeStart":358,"sourceCodeEnd":394,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/packages/cli/src/utils/sandbox.ts#L358-L394","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["For the local dev image: run `npm run build:all` or `npm run build:sandbox` in the gemini-cli repo to build it locally.","For an external image: verify the image name and tag in your sandbox config, and confirm `docker pull <image>` (or podman) succeeds manually.","Check network connectivity / proxy settings for the container registry, and ensure the daemon is running (`docker info`)."],"exampleFix":"// before: image missing, no build done\n// config.image = 'gemini-sandbox:dev'  (LOCAL_DEV_SANDBOX_IMAGE_NAME)\n\n// after: build it locally first\n// npm run build:sandbox   # in gemini-cli repo\n// gemini --sandbox","handlingStrategy":"try-catch","validationCode":"// Pre-flight: ensure the image is present or buildable before starting the sandbox.\nconst { execSync } = require('child_process');\nconst image = config.image;\ntry {\n  execSync(`docker image inspect ${image}`, {stdio:'ignore'});\n} catch {\n  if (image === LOCAL_DEV_SANDBOX_IMAGE_NAME) {\n    execSync('npm run build:sandbox', {cwd: geminiRepoRoot, stdio:'inherit'});\n  } else {\n    execSync(`docker pull ${image}`, {stdio:'inherit'});\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  await startSandbox(config);\n} catch (e) {\n  if (e instanceof FatalSandboxError && /missing or could not be pulled/.test(e.message)) {\n    // build/pull then retry once, else surface a user-facing message\n  } else throw e;\n}","preventionTips":["Run `npm run build:sandbox` as part of your dev-env bootstrap script so the local image always exists.","Add a CI step that verifies the configured image is pullable before deploying."],"tags":["sandbox","docker","container-image","network","registry"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}