google-gemini/gemini-cli · error · Error

OAuth2 authentication for agent "${this.agentName}" requires

Error message

OAuth2 authentication for agent "${this.agentName}" requires authorization_url and token_url. Provide them in the auth config or ensure the agent card exposes an oauth2 security scheme.

What it means

The OAuth2 flow needs authorization_url and token_url. The provider tries to discover them from the agent card's oauth2 security scheme (fetchAgentCardDefaults/mergeAgentCardDefaults) and falls back to config values. If neither source yields both URLs, authenticateInteractively refuses to start. The error tells the user to supply them or ensure the card exposes the scheme.

Source

Thrown at packages/core/src/agents/auth-provider/oauth2-provider.ts:219

    } catch (error) {
      debugLogger.warn(
        `[OAuth2AuthProvider] Could not fetch agent card for OAuth URL discovery: ${getErrorMessage(error)}`,
      );
    }
  }

  /**
   * Run a full OAuth 2.0 Authorization Code + PKCE flow through the browser.
   */
  private async authenticateInteractively(): Promise<OAuthToken> {
    if (!this.config.client_id) {
      throw new Error(
        `OAuth2 authentication for agent "${this.agentName}" requires a client_id. ` +
          'Add client_id to the auth config in your agent definition.',
      );
    }
    if (!this.authorizationUrl || !this.tokenUrl) {
      throw new Error(
        `OAuth2 authentication for agent "${this.agentName}" requires authorization_url and token_url. ` +
          'Provide them in the auth config or ensure the agent card exposes an oauth2 security scheme.',
      );
    }

    const flowConfig: OAuthFlowConfig = {
      clientId: this.config.client_id,
      clientSecret: this.config.client_secret,
      authorizationUrl: this.authorizationUrl,
      tokenUrl: this.tokenUrl,
      scopes: this.scopes,
    };

    const pkceParams = generatePKCEParams();
    const preferredPort = getPortFromUrl(flowConfig.redirectUri);
    const callbackServer = startCallbackServer(pkceParams.state, preferredPort);
    const redirectPort = await callbackServer.port;

View on GitHub (pinned to 5024443c72)

Solutions

1. Add authorization_url and token_url to the auth config in the frontmatter.
2. Ensure the agent card exposes an oauth2 security scheme with the correct flow URLs.
3. Confirm agent_card_url is reachable from the runtime so discovery can populate the URLs.
4. Check fetchAgentCardDefaults warnings in debug logs for discovery failures.

Example fix

# before - expecting card to supply URLs but it did not
auth:
  type: oauth
  client_id: my-id

# after
auth:
  type: oauth
  client_id: my-id
  authorization_url: https://auth.example/authorize
  token_url: https://auth.example/token

if (authConfig.type === 'oauth2'
    && (!authConfig.authorization_url || !authConfig.token_url)) {
  throw new Error('oauth2 requires authorization_url and token_url (or an agent card that exposes them).');
}
await A2AAuthProviderFactory.create({ authConfig, agentName, agentCardUrl });

function hasOAuthUrls(c: { authorization_url?: string; token_url?: string }): boolean {
  return typeof c.authorization_url === 'string' && typeof c.token_url === 'string';
}

When it happens

Trigger: Agent card unreachable so fetchAgentCardDefaults warned and skipped; the card has no securitySchemes or none of type oauth2; config omits authorization_url/token_url; the card was fetched but the scheme names differ from what the merger expects.

Common situations: agent_card_url behind a firewall during discovery; a server whose card uses a non-standard security scheme key; local-only testing where the card endpoint is not served; config edited to remove the URLs assuming the card would supply them.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• OAuth2 authentication for agent "${this.agentName}" requires
• The enforced authentication type is '${enforcedType}', but t
• The auth type '${enforcedType}' is enforced, but no authenti
• Please set an Auth method in your ${USER_SETTINGS_PATH} or s
• Authentication cancelled by user.

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