Please set an Auth method in your ${USER_SETTINGS_PATH} or s

Error message

Please set an Auth method in your ${USER_SETTINGS_PATH} or specify one of the following environment variables before running: GEMINI_API_KEY, GOOGLE_GENAI_USE_VERTEXAI, GOOGLE_GENAI_USE_GCA

What it means

Thrown when no `enforcedType` is set and the effective auth type resolves to a falsy value — i.e. the caller has not configured any authentication at all. The message names the user settings path and the three environment variables (`GEMINI_API_KEY`, `GOOGLE_GENAI_USE_VERTEXAI`, `GOOGLE_GENAI_USE_GCA`) that would resolve an auth type, giving the user a concrete checklist.

Source

Thrown at packages/cli/src/validateNonInterActiveAuth.ts:39

  configuredAuthType: AuthType | undefined,
  useExternalAuth: boolean | undefined,
  nonInteractiveConfig: Config,
  settings: LoadedSettings,
) {
  try {
    const effectiveAuthType = configuredAuthType || getAuthTypeFromEnv();

    const enforcedType = settings.merged.security.auth.enforcedType;
    if (enforcedType && effectiveAuthType !== enforcedType) {
      const message = effectiveAuthType
        ? `The enforced authentication type is '${enforcedType}', but the current type is '${effectiveAuthType}'. Please re-authenticate with the correct type.`
        : `The auth type '${enforcedType}' is enforced, but no authentication is configured.`;
      throw new Error(message);
    }

    if (!effectiveAuthType) {
      const message = `Please set an Auth method in your ${USER_SETTINGS_PATH} or specify one of the following environment variables before running: GEMINI_API_KEY, GOOGLE_GENAI_USE_VERTEXAI, GOOGLE_GENAI_USE_GCA`;
      throw new Error(message);
    }

    const authType: AuthType = effectiveAuthType;

    if (!useExternalAuth) {
      const err = await validateAuthMethod(String(authType));
      if (err != null) {
        throw new Error(err);
      }
    }

    return authType;
  } catch (error) {
    if (nonInteractiveConfig.getOutputFormat() === OutputFormat.JSON) {
      handleError(
        error instanceof Error ? error : new Error(String(error)),
        nonInteractiveConfig,
        ExitCodes.FATAL_AUTHENTICATION_ERROR,

View on GitHub (pinned to 5024443c72)

Solutions

Set one of the listed environment variables before invoking the CLI (quickest: `GEMINI_API_KEY`).
Run the CLI once interactively to choose and persist an auth method in the user settings file.
Manually edit the user settings file to add an `selectedAuthType` / auth block.
If running in CI, inject the chosen credential via the CI secret store as the matching env var.

Example fix

# before
$ gemini -p 'hi'  # no creds anywhere

# after
$ export GEMINI_API_KEY=AIza...
$ gemini -p 'hi'

Defensive patterns

Strategy: validation

Validate before calling

function assertAnyAuthConfigured(effectiveType: string | undefined) {
  if (!effectiveType) {
    throw new Error(
      'No auth configured. Set GEMINI_API_KEY, run interactive login, or set an auth type in settings.',
    );
  }
}

assertAnyAuthConfigured(configuredAuthType ?? getAuthTypeFromEnv());

Type guard

function hasAnyAuth(env: NodeJS.ProcessEnv): boolean {
  return Boolean(
    env.GEMINI_API_KEY ||
      env.GOOGLE_GENAI_USE_VERTEXAI ||
      env.GOOGLE_GENAI_USE_GCA,
  );
}

Try / catch

try {
  await validateNonInteractiveAuth(configuredAuthType, useExternalAuth, cfg, settings);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Please set an Auth method')) {
    // open onboarding / set env, then retry
  }
  throw e;
}

Prevention

Always set an auth env var in CI templates, even for smoke tests.
Run interactive login once on dev machines to seed the settings file.
Add a `gemini doctor` style preflight that checks auth state.

When it happens

Trigger: First-time headless run with no prior OAuth login, no API key in env, and no auth type written to the user settings file. `configuredAuthType` is empty, `getAuthTypeFromEnv()` returns undefined, and `enforcedType` is unset so the earlier branch is skipped.

Common situations: Brand-new install where the user skipped interactive setup; env vars lost after a shell change; running in CI without provisioning a key; the settings file at `USER_SETTINGS_PATH` is empty or missing.

Related errors

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