google-gemini/gemini-cli · error · Error

Invalid environment variable name: "${key}". Must contain on

Error message

Invalid environment variable name: "${key}". Must contain only alphanumeric characters and underscores.

What it means

Thrown by formatEnvContent() when an environment variable name (key) fails the regex /^[a-zA-Z_][a-zA-Z0-9_]*$/. The library writes a .env-style file, so keys must be valid shell identifiers; any other character set would produce an unparseable or insecure env file.

Source

Thrown at packages/cli/src/config/extensions/extensionSettings.ts:145

  const envContent = formatEnvContent(nonSensitiveSettings);

  if (fsSync.existsSync(envFilePath)) {
    const stat = fsSync.statSync(envFilePath);
    if (stat.isDirectory()) {
      throw new Error(
        `Cannot write extension settings to ${envFilePath} because it is a directory.`,
      );
    }
  }

  await fs.writeFile(envFilePath, envContent);
}

function formatEnvContent(settings: Record<string, string>): string {
  let envContent = '';
  for (const [key, value] of Object.entries(settings)) {
    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(key)) {
      throw new Error(
        `Invalid environment variable name: "${key}". Must contain only alphanumeric characters and underscores.`,
      );
    }
    if (value.includes('\n') || value.includes('\r')) {
      throw new Error(
        `Invalid environment variable value for "${key}". Values cannot contain newlines.`,
      );
    }
    const formattedValue = value.includes(' ')
      ? `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`
      : value;
    envContent += `${key}=${formattedValue}\n`;
  }
  return envContent;
}

export async function promptForSetting(
  setting: ExtensionSetting,

View on GitHub (pinned to 5024443c72)

Solutions

1. Rename the offending envVar in the extension setting definition to a valid identifier (letters, digits, underscores; not starting with a digit).
2. Sanitize keys before they reach writeExtensionSettings: replace invalid characters with underscores.
3. Add a manifest validator that rejects invalid envVar names at extension load time.

Example fix

// before
envVar: 'my-extension.key'
// after
envVar: 'MY_EXTENSION_KEY'

const ENV_VAR_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
function sanitizeEnvVar(name: string): string {
  return name.replace(/[^a-zA-Z0-9_]/g, '_').replace(/^[0-9]/, '_$1');
}
function assertValidEnvVar(name: string) {
  if (!ENV_VAR_RE.test(name)) throw new Error(`Invalid env var name: ${name}`);
}

function isValidEnvVarName(name: string): boolean { return /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name); }

When it happens

Trigger: An extension declares a setting whose envVar contains characters outside [A-Za-z0-9_], starts with a digit, or is empty. The formatter iterates Object.entries(nonSensitiveSettings) and validates every key.

Common situations: A migration config uses keys with dashes (my-var), dots (section.key), or spaces; a typo in the extension manifest envVar; generated keys from user input that were not sanitized.

Related errors

• Invalid environment variable value for "${key}". Values cann
• Invalid approval mode: ${rawApprovalMode}. Valid values are:
• Invalid regex pattern in allowedExtensions setting: "${patte
• Cannot write extension settings to ${envFilePath} because it
• Invalid scope: ${argv.scope}. Please use one of ${Object.val

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