google-gemini/gemini-cli · error · FatalSandboxError

Cannot build sandbox using installed gemini binary; run `npm

Error message

Cannot build sandbox using installed gemini binary; run `npm link ./packages/cli` under gemini-cli repo to switch to linked binary.

What it means

Thrown when the BUILD_SANDBOX environment variable is set but the running gemini binary is the globally/npm-installed version rather than a development-linked one. The build path requires reaching into the gemini-cli source tree (gemini-cli/packages/) to run scripts/build_sandbox.js, which only exists relative to a cloned repo. This is a developer-workflow guard, not a runtime defect in user code.

Source

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

    const projectSandboxDockerfile = path.join(
      GEMINI_DIR,
      'sandbox.Dockerfile',
    );
    const isCustomProjectSandbox = fs.existsSync(projectSandboxDockerfile);

    const image = config.image;
    if (!image) throw new FatalSandboxError('Sandbox image is required');
    if (!/^[a-zA-Z0-9_.:/-]+$/.test(image))
      throw new FatalSandboxError('Invalid sandbox image name');
    const workdir = path.resolve(process.cwd());
    const containerWorkdir = getContainerPath(workdir);

    // if BUILD_SANDBOX is set, then call scripts/build_sandbox.js under gemini-cli repo
    //
    // note this can only be done with binary linked from gemini-cli repo
    if (process.env['BUILD_SANDBOX']) {
      if (!gcPath.includes('gemini-cli/packages/')) {
        throw new FatalSandboxError(
          'Cannot build sandbox using installed gemini binary; ' +
            'run `npm link ./packages/cli` under gemini-cli repo to switch to linked binary.',
        );
      } else {
        debugLogger.log('building sandbox ...');
        const gcRoot = gcPath.split('/packages/')[0];
        // if project folder has sandbox.Dockerfile under project settings folder, use that
        let buildArgs = '';
        const projectSandboxDockerfile = path.join(
          GEMINI_DIR,
          'sandbox.Dockerfile',
        );
        if (isCustomProjectSandbox) {
          debugLogger.log(`using ${projectSandboxDockerfile} for sandbox`);
          buildArgs += `-f ${path.resolve(projectSandboxDockerfile)} -i ${image}`;
        }
        execSync(
          `cd ${gcRoot} && node scripts/build_sandbox.js -s ${buildArgs}`,

View on GitHub (pinned to 5024443c72)

Solutions

1. Clone the gemini-cli repo, then run `npm link ./packages/cli` from the repo root to make the `gemini` command resolve to the local source tree.
2. Verify the link with `which gemini` — it should point into .../gemini-cli/packages/cli, not a global node_modules.
3. If you did not intend to build the sandbox image from source, unset BUILD_SANDBOX and rely on the prebuilt/published image instead.

Example fix

// before: running installed binary with build flag
// BUILD_SANDBOX=1 gemini

// after: link dev binary first
// cd ~/gemini-cli && npm link ./packages/cli
// BUILD_SANDBOX=1 gemini

// Before setting BUILD_SANDBOX, confirm the gemini binary is a dev link.
const gcPath = require('child_process').execSync('which gemini', {encoding:'utf8'}).trim();
if (process.env.BUILD_SANDBOX && !gcPath.includes('gemini-cli/packages/')) {
  throw new Error('Run `npm link ./packages/cli` in the gemini-cli repo before enabling BUILD_SANDBOX.');
}

When it happens

Trigger: Setting BUILD_SANDBOX=1 while invoking the gemini CLI installed via npm (gcPath does not contain 'gemini-cli/packages/'). The code checks process.env['BUILD_SANDBOX'] and then tests whether gcPath includes the repo subpath; any mismatch throws.

Common situations: A contributor enables BUILD_SANDBOX to test a Dockerfile change but forgot to run `npm link ./packages/cli` after cloning. Running the published binary (e.g. npx @google/gemini-cli) with BUILD_SANDBOX set. Switching between linked and installed binaries without re-linking.

Related errors

• Path '${from}' listed in SANDBOX_MOUNTS must be absolute
• SANDBOX_ENV must be a comma-separated list of key=value pair
• runsc (gVisor) requires Docker. Install Docker, or use sandb
• GEMINI_SANDBOX is true but failed to determine command for s
• Sandbox image '${image}' is missing or could not be pulled.

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