{"record":{"id":"bc7a0b2a1fefa369","repo":"google-gemini/gemini-cli","slug":"sandbox-env-must-be-a-comma-separated-list-of-key","errorCode":null,"errorMessage":"SANDBOX_ENV must be a comma-separated list of key=value pairs","messagePattern":"SANDBOX_ENV must be a comma-separated list of key=value pairs","errorType":"validation","errorClass":"FatalSandboxError","httpStatus":null,"severity":"error","filePath":"packages/cli/src/utils/sandbox.ts","lineNumber":699,"sourceCode":"      args.push(\n        '--volume',\n        `${sandboxVenvPath}:${getContainerPath(process.env['VIRTUAL_ENV'])}`,\n      );\n      args.push(\n        '--env',\n        `VIRTUAL_ENV=${getContainerPath(process.env['VIRTUAL_ENV'])}`,\n      );\n    }\n\n    // copy additional environment variables from SANDBOX_ENV\n    if (process.env['SANDBOX_ENV']) {\n      for (let env of process.env['SANDBOX_ENV'].split(',')) {\n        if ((env = env.trim())) {\n          if (env.includes('=')) {\n            debugLogger.log(`SANDBOX_ENV: ${env}`);\n            args.push('--env', env);\n          } else {\n            throw new FatalSandboxError(\n              'SANDBOX_ENV must be a comma-separated list of key=value pairs',\n            );\n          }\n        }\n      }\n    }\n\n    // copy NODE_OPTIONS\n    const existingNodeOptions = process.env['NODE_OPTIONS'] || '';\n    const allNodeOptions = [\n      ...(existingNodeOptions ? [existingNodeOptions] : []),\n      ...nodeArgs,\n    ].join(' ');\n\n    if (allNodeOptions.length > 0) {\n      args.push('--env', `NODE_OPTIONS=\"${allNodeOptions}\"`);\n    }\n","sourceCodeStart":681,"sourceCodeEnd":717,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/packages/cli/src/utils/sandbox.ts#L681-L717","documentation":"Thrown while parsing the SANDBOX_ENV environment variable for the Docker/podman sandbox path when an entry lacks an `=` sign. SANDBOX_ENV must be a comma-separated list of KEY=VALUE pairs that are forwarded as --env flags to the container. An entry without `=` cannot be a valid environment assignment.","triggerScenarios":"SANDBOX_ENV contains an entry without `=`, e.g. `SANDBOX_ENV=FOO,BAR=baz` — the `FOO` token triggers the throw. The code does env.trim() then checks env.includes('=').","commonSituations":"User intends to forward a variable by name only (like docker --env FOO) but this implementation requires explicit KEY=VALUE. Trailing comma producing an empty token is handled, but a bare name is not. Copying a value that contained a comma inside it (e.g. a list) and forgetting to quote/escape.","solutions":["Rewrite each SANDBOX_ENV entry as KEY=VALUE, e.g. SANDBOX_ENV=FOO=bar,BAR=baz.","If you only have a variable name, expand it: SANDBOX_ENV=FOO=$FOO.","Sanitize any value containing commas (use a different delimiter or base64-encode complex values)."],"exampleFix":"// before\n// SANDBOX_ENV=DEBUG,LOG_LEVEL=info\n\n// after\n// SANDBOX_ENV=DEBUG=true,LOG_LEVEL=info","handlingStrategy":"validation","validationCode":"function validateSandboxEnv(envStr) {\n  for (const raw of (envStr || '').split(',')) {\n    const env = raw.trim();\n    if (!env) continue;\n    if (!env.includes('=')) {\n      throw new Error(`SANDBOX_ENV entry '${env}' must be KEY=VALUE`);\n    }\n  }\n}","typeGuard":"const isValidEnvPair = (entry) =>\n  typeof entry === 'string' && entry.trim().length > 0 && entry.includes('=');","tryCatchPattern":null,"preventionTips":["Always write SANDBOX_ENV as KEY=VALUE, expanding variables explicitly.","Avoid embedding commas in values."],"tags":["sandbox","docker","environment-variable","validation"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}