google-gemini/gemini-cli · error · Error

Failed to create auth provider for agent '${this.definition.

Error message

Failed to create auth provider for agent '${this.definition.name}'

What it means

Thrown by RemoteSubagentProtocol._getAuthHandler() when A2AAuthProviderFactory.create() returns undefined despite definition.auth being set. The factory returns undefined when authConfig is falsy or when an AgentCard declares security schemes but no authConfig was provided to match them. Since _getAuthHandler only calls the factory when definition.auth is truthy, the undefined return indicates the factory could not build a provider for the given auth type — most commonly because the agent card requires authentication schemes the configured auth does not satisfy.

Source

Thrown at packages/core/src/agents/remote-subagent-protocol.ts:302

    this._resultResolve({
      llmContent: [{ text: finalOutput }],
      returnDisplay: finalProgress,
    });
  }

  private async _getAuthHandler(): Promise<AuthenticationHandler | undefined> {
    if (this.authHandler) return this.authHandler;
    if (!this.definition.auth) return undefined;

    const targetUrl = getRemoteAgentTargetUrl(this.definition);
    const provider = await A2AAuthProviderFactory.create({
      authConfig: this.definition.auth,
      agentName: this.definition.name,
      targetUrl,
      agentCardUrl: this.definition.agentCardUrl,
    });
    if (!provider) {
      throw new Error(
        `Failed to create auth provider for agent '${this.definition.name}'`,
      );
    }
    this.authHandler = provider;
    return this.authHandler;
  }

  // ---------------------------------------------------------------------------
  // Internal helpers
  // ---------------------------------------------------------------------------

  private _emit(events: AgentEvent[]): void {
    if (events.length === 0) return;
    const subscribers = [...this._subscribers];
    for (const event of events) {
      this._events.push(event);
      if (event.type === 'agent_end') {
        this._agentEndEmitted = true;

View on GitHub (pinned to 5024443c72)

Solutions

Inspect the agent definition's auth block: ensure type is one of 'google-credentials', 'apiKey', 'http', or 'oauth2' and all required fields for that type are present.
Run A2AAuthProviderFactory.validateAuthConfig(authConfig, agentCard.securitySchemes) before starting the stream to catch scheme mismatches early.
Verify that the agent card's securitySchemes are satisfiable by the configured auth type; adjust either the card or the auth config to match.
If the agent requires no auth, remove the auth block from the definition rather than leaving an incomplete one.

Example fix

// before — auth block present but factory returns undefined
const def: RemoteAgentDefinition = {
  name: 'my-agent',
  auth: { type: 'apiKey' }, // missing required fields
  agentCardUrl: 'https://...',
};

// after — validate against card schemes first
const result = A2AAuthProviderFactory.validateAuthConfig(def.auth, card.securitySchemes);
if (!result.valid) {
  throw new Error(`Auth misconfigured: ${result.diff?.missingConfig.join(', ')}`);
}

Defensive patterns

Strategy: validation

Validate before calling

// Validate auth config against the agent card before starting the stream
const result = A2AAuthProviderFactory.validateAuthConfig(
  definition.auth,
  agentCard?.securitySchemes,
);
if (!result.valid) {
  throw new Error(
    `Auth misconfigured for '${definition.name}': ${result.diff?.missingConfig.join(', ')}`
  );
}

Type guard

import type { A2AAuthConfig } from './auth-provider/types.js';

function hasValidAuthConfig(
  def: RemoteAgentDefinition
): def is RemoteAgentDefinition & { auth: A2AAuthConfig } {
  return def.auth != null && typeof def.auth.type === 'string';
}

Try / catch

try {
  await protocol.send(query);
} catch (e) {
  if (e instanceof Error && e.message.includes('Failed to create auth provider')) {
    // Prompt user to reconfigure auth for this agent
    return { error: `Reconfigure authentication for agent '${name}'.` };
  }
  throw e;
}

Prevention

Run validateAuthConfig at agent registration time, not just at call time.
Document required auth fields for each auth type in agent definition schemas.
Test each auth type (apiKey, http, oauth2, google-credentials) in isolation.
Add Zod schema validation for the auth block to catch missing fields early.

When it happens

Trigger: A remote agent definition has an auth block set, but A2AAuthProviderFactory.create() returns undefined. This happens when definition.auth is present yet the factory's internal logic cannot map it to a concrete provider — e.g., the agent card's securitySchemes are non-empty but authConfig doesn't match any, or the factory's early-return paths fire.

Common situations: Misconfigured auth block in a remote agent definition (e.g., type field missing or typo'd); agent card requires OAuth2 but auth config only specifies apiKey; version mismatch where the factory was updated to require additional fields (targetUrl, agentCardUrl) that the definition doesn't provide; JSON-based agent card whose security schemes differ from what the auth config targets.

Related errors

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