google-gemini/gemini-cli · critical · Error

[${logPrefix}] Unable to set GeneratorConfig. Please provide

Error message

[${logPrefix}] Unable to set GeneratorConfig. Please provide a GEMINI_API_KEY or set USE_CCPA.

What it means

Plain Error thrown by refreshAuthentication in the final else branch: neither USE_CCPA nor GEMINI_API_KEY is present in the resolved environment. The executor cannot pick any authentication strategy to build the GeneratorConfig, so it refuses to start. The same message is logged at error level before throwing.

Source

Thrown at packages/a2a-server/src/config/config.ts:655

          );
        }
        throw e;
      }
    }

    logger.info(
      `[${logPrefix}] GOOGLE_CLOUD_PROJECT: ${getEnvLocal('GOOGLE_CLOUD_PROJECT')}`,
    );
  } else if (getEnvLocal('GEMINI_API_KEY')) {
    logger.info(`[${logPrefix}] Using Gemini API Key`);
    await config.refreshAuth(
      AuthType.USE_GEMINI,
      getEnvLocal('GEMINI_API_KEY'),
    );
  } else {
    const errorMessage = `[${logPrefix}] Unable to set GeneratorConfig. Please provide a GEMINI_API_KEY or set USE_CCPA.`;
    logger.error(errorMessage);
    throw new Error(errorMessage);
  }
}

View on GitHub (pinned to 5024443c72)

Solutions

Set GEMINI_API_KEY in the environment (or in ~/.gemini/.env for untrusted workspaces).
Or set USE_CCPA=true along with valid compute credentials.
If using a workspace .env, ensure the workspace is trusted so loadEnvironment reads it.
Confirm the env var isn't being shadowed by an empty value (export GEMINI_API_KEY= with no value still fails the getEnvLocal check).

Example fix

# before
# no auth env vars set

# after
export GEMINI_API_KEY=AIza...
# or
export USE_CCPA=true
export GOOGLE_APPLICATION_CREDENTIALS=/secrets/sa.json

Defensive patterns

Strategy: validation

Validate before calling

function hasAuthStrategy(env: NodeJS.ProcessEnv): boolean {
  return env['USE_CCPA'] === 'true' || !!env['GEMINI_API_KEY'];
}
if (!hasAuthStrategy(process.env)) {
  throw new Error('Missing auth: set GEMINI_API_KEY or USE_CCPA before starting the agent.');
}

Prevention

Set GEMINI_API_KEY or USE_CCPA in the deployment env (or ~/.gemini/.env for untrusted workspaces).
Mark the workspace trusted if you need to load auth from a workspace-level .env.
Fail fast at startup with a clear message rather than letting the first task hit this.
Beware empty values: USE_CCPA='' is falsy and won't satisfy the check.

When it happens

Trigger: Server startup or task creation with no auth env vars after loadEnvironment merges workspace .env files - both USE_CCPA and GEMINI_API_KEY are absent/empty. Common in fresh deployments that forgot to provision credentials.

Common situations: Fresh clone without .env; CI without injected secrets; .env file under the workspace ignored because the workspace is untrusted (loadEnvironment bypasses workspace .env for untrusted workspaces and only reads home).

Related errors

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