What causes "SANDBOX_ENV must be a comma-separated list of key=value pairs" in google-gemini/gemini-cli?

Rewrite each SANDBOX_ENV entry as KEY=VALUE, e.g. SANDBOX_ENV=FOO=bar,BAR=baz.

google-gemini/gemini-cli · error · FatalSandboxError

SANDBOX_ENV must be a comma-separated list of key=value pair

Error message

SANDBOX_ENV must be a comma-separated list of key=value pairs

What it means

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.

Source

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

      args.push(
        '--volume',
        `${sandboxVenvPath}:${getContainerPath(process.env['VIRTUAL_ENV'])}`,
      );
      args.push(
        '--env',
        `VIRTUAL_ENV=${getContainerPath(process.env['VIRTUAL_ENV'])}`,
      );
    }

    // copy additional environment variables from SANDBOX_ENV
    if (process.env['SANDBOX_ENV']) {
      for (let env of process.env['SANDBOX_ENV'].split(',')) {
        if ((env = env.trim())) {
          if (env.includes('=')) {
            debugLogger.log(`SANDBOX_ENV: ${env}`);
            args.push('--env', env);
          } else {
            throw new FatalSandboxError(
              'SANDBOX_ENV must be a comma-separated list of key=value pairs',
            );
          }
        }
      }
    }

    // copy NODE_OPTIONS
    const existingNodeOptions = process.env['NODE_OPTIONS'] || '';
    const allNodeOptions = [
      ...(existingNodeOptions ? [existingNodeOptions] : []),
      ...nodeArgs,
    ].join(' ');

    if (allNodeOptions.length > 0) {
      args.push('--env', `NODE_OPTIONS="${allNodeOptions}"`);
    }

View on GitHub (pinned to 5024443c72)

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).

Example fix

// before
// SANDBOX_ENV=DEBUG,LOG_LEVEL=info

// after
// SANDBOX_ENV=DEBUG=true,LOG_LEVEL=info

Defensive patterns

Strategy: validation

Validate before calling

function validateSandboxEnv(envStr) {
  for (const raw of (envStr || '').split(',')) {
    const env = raw.trim();
    if (!env) continue;
    if (!env.includes('=')) {
      throw new Error(`SANDBOX_ENV entry '${env}' must be KEY=VALUE`);
    }
  }
}

Type guard

const isValidEnvPair = (entry) =>
  typeof entry === 'string' && entry.trim().length > 0 && entry.includes('=');

Prevention

Always write SANDBOX_ENV as KEY=VALUE, expanding variables explicitly.
Avoid embedding commas in values.

When it happens

Trigger: 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('=').

Common situations: 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.

Related errors

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