{"record":{"id":"7724316acbd73b18","repo":"google-gemini/gemini-cli","slug":"environment-variable-envvar-is-not-set-or-is","errorCode":null,"errorMessage":"Environment variable '${envVar}' is not set or is empty. Please set it before using this agent.","messagePattern":"Environment variable '(.+?)' is not set or is empty\\. Please set it before using this agent\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/agents/auth-provider/value-resolver.ts","lineNumber":38,"sourceCode":" * - Any other string: Use as literal value\n *\n * @param value The value to resolve\n * @returns The resolved value\n * @throws Error if environment variable is not set or command fails\n */\nexport async function resolveAuthValue(value: string): Promise<string> {\n  // Support escaping with double prefix (e.g. $$ or !!).\n  // Strips one prefix char: $$FOO → $FOO, !!cmd → !cmd (literal, not resolved).\n  if (value.startsWith('$$') || value.startsWith('!!')) {\n    return value.slice(1);\n  }\n\n  // Environment variable: $MY_VAR\n  if (value.startsWith('$')) {\n    const envVar = value.slice(1);\n    const resolved = process.env[envVar];\n    if (resolved === undefined || resolved === '') {\n      throw new Error(\n        `Environment variable '${envVar}' is not set or is empty. ` +\n          `Please set it before using this agent.`,\n      );\n    }\n    debugLogger.debug(`[AuthValueResolver] Resolved env var: ${envVar}`);\n    return resolved;\n  }\n\n  // Shell command: !command arg1 arg2\n  if (value.startsWith('!')) {\n    const command = value.slice(1).trim();\n    if (!command) {\n      throw new Error('Empty command in auth value. Expected format: !command');\n    }\n\n    debugLogger.debug(`[AuthValueResolver] Executing command for auth value`);\n\n    const shellConfig = getShellConfiguration();","sourceCodeStart":20,"sourceCodeEnd":56,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/packages/core/src/agents/auth-provider/value-resolver.ts#L20-L56","documentation":"Thrown by resolveAuthValue when a value beginning with '$' names an environment variable that process.env reports as undefined or the empty string. The function is the central resolver for $VAR / !cmd / literal auth values, so this fires for any agent auth field (API key, bearer token, basic password) that uses the $ sigil.","triggerScenarios":"resolveAuthValue('$MY_API_KEY') is called (transitively from any A2A auth provider that resolves config strings) where process.env.MY_API_KEY is undefined or ''. The double-prefix escape ($$FOO) is the only way to get a literal $FOO, so a single $ always triggers env lookup.","commonSituations":"Env var typo (case mismatch like $Api_Key vs $API_KEY); forgot to export the var in the shell profile; .env file not loaded in the process that runs the agent; var set in a different shell session; CI secret not injected; var explicitly set to empty string.","solutions":["Check the exact variable name spelling and case against what is in the environment: print process.env keys around the failing agent.","Export the variable in the shell/profile that launches the process (export MY_API_KEY=...).","If using a .env loader, confirm it runs before the agent auth config is resolved.","To use a literal value that starts with $, escape it as $$VALUE so the resolver strips one $ and returns the literal.","If the value should genuinely come from a command instead, use the ! sigil (!gcloud auth print-access-token)."],"exampleFix":"# before\nexport apikey='$API_KEY'   # shell expands empty / var unset at resolution\n\n# after\nexport API_KEY='real-secret-value'\n# agent config:\napiKey: '$API_KEY'","handlingStrategy":"validation","validationCode":"import { needsResolution } from './value-resolver.js';\nfunction ensureEnvVars(values) {\n  for (const v of values) {\n    if (v.startsWith('$') && !v.startsWith('$$')) {\n      const name = v.slice(1);\n      if (process.env[name] === undefined || process.env[name] === '')\n        throw new Error(`Missing env var ${name}`);\n    }\n  }\n}\n// Call before constructing the agent / auth provider.","typeGuard":"function isResolvableEnvValue(v: string): boolean {\n  return v.startsWith('$') && !v.startsWith('$$');\n}","tryCatchPattern":"try {\n  const resolved = await resolveAuthValue('$API_KEY');\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Environment variable')) {\n    // prompt user / load .env / fall back to interactive entry\n  }\n  throw e;\n}","preventionTips":["Validate all $-prefixed auth values at startup, before any agent runs.","Keep env var names in a single constant map to avoid typos.","Use $$ to escape literal $-prefixed values."],"tags":["auth","environment","config"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}