{"record":{"id":"0cf0a2141bc2a1a5","repo":"google-gemini/gemini-cli","slug":"cannot-build-sandbox-using-installed-gemini-binary","errorCode":null,"errorMessage":"Cannot build sandbox using installed gemini binary; run `npm link ./packages/cli` under gemini-cli repo to switch to linked binary.","messagePattern":"Cannot build sandbox using installed gemini binary; run `npm link \\./packages/cli` under gemini-cli repo to switch to linked binary\\.","errorType":"exception","errorClass":"FatalSandboxError","httpStatus":null,"severity":"error","filePath":"packages/cli/src/utils/sandbox.ts","lineNumber":340,"sourceCode":"    const projectSandboxDockerfile = path.join(\n      GEMINI_DIR,\n      'sandbox.Dockerfile',\n    );\n    const isCustomProjectSandbox = fs.existsSync(projectSandboxDockerfile);\n\n    const image = config.image;\n    if (!image) throw new FatalSandboxError('Sandbox image is required');\n    if (!/^[a-zA-Z0-9_.:/-]+$/.test(image))\n      throw new FatalSandboxError('Invalid sandbox image name');\n    const workdir = path.resolve(process.cwd());\n    const containerWorkdir = getContainerPath(workdir);\n\n    // if BUILD_SANDBOX is set, then call scripts/build_sandbox.js under gemini-cli repo\n    //\n    // note this can only be done with binary linked from gemini-cli repo\n    if (process.env['BUILD_SANDBOX']) {\n      if (!gcPath.includes('gemini-cli/packages/')) {\n        throw new FatalSandboxError(\n          'Cannot build sandbox using installed gemini binary; ' +\n            'run `npm link ./packages/cli` under gemini-cli repo to switch to linked binary.',\n        );\n      } else {\n        debugLogger.log('building sandbox ...');\n        const gcRoot = gcPath.split('/packages/')[0];\n        // if project folder has sandbox.Dockerfile under project settings folder, use that\n        let buildArgs = '';\n        const projectSandboxDockerfile = path.join(\n          GEMINI_DIR,\n          'sandbox.Dockerfile',\n        );\n        if (isCustomProjectSandbox) {\n          debugLogger.log(`using ${projectSandboxDockerfile} for sandbox`);\n          buildArgs += `-f ${path.resolve(projectSandboxDockerfile)} -i ${image}`;\n        }\n        execSync(\n          `cd ${gcRoot} && node scripts/build_sandbox.js -s ${buildArgs}`,","sourceCodeStart":322,"sourceCodeEnd":358,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/packages/cli/src/utils/sandbox.ts#L322-L358","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Verify the link with `which gemini` — it should point into .../gemini-cli/packages/cli, not a global node_modules.","If you did not intend to build the sandbox image from source, unset BUILD_SANDBOX and rely on the prebuilt/published image instead."],"exampleFix":"// before: running installed binary with build flag\n// BUILD_SANDBOX=1 gemini\n\n// after: link dev binary first\n// cd ~/gemini-cli && npm link ./packages/cli\n// BUILD_SANDBOX=1 gemini","handlingStrategy":"validation","validationCode":"// Before setting BUILD_SANDBOX, confirm the gemini binary is a dev link.\nconst gcPath = require('child_process').execSync('which gemini', {encoding:'utf8'}).trim();\nif (process.env.BUILD_SANDBOX && !gcPath.includes('gemini-cli/packages/')) {\n  throw new Error('Run `npm link ./packages/cli` in the gemini-cli repo before enabling BUILD_SANDBOX.');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep a single source of truth for your dev gemini binary via `npm link` and verify with `which gemini` after each switch.","Document the BUILD_SANDBOX + npm-link pairing in your team onboarding so contributors do not enable one without the other."],"tags":["sandbox","developer-workflow","docker","environment-variable","npm-link"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}