mastra-ai/mastra · error

Unknown OAuth provider: ${providerId}

Error message

Unknown OAuth provider: ${providerId}

What it means

OAuthStorage.login looks up the provider implementation via getOAuthProvider(providerId). If no provider is registered under that id, it throws before any network call. Only ids registered in the provider registry are valid.

Source

Thrown at mastracode/sdk/src/auth/storage.ts:193

   */
  loadStoredApiKeysIntoEnv(providerEnvVars: Record<string, string | undefined>): void {
    for (const [key, cred] of Object.entries(this.data)) {
      if (!key.startsWith('apikey:') || cred.type !== 'api_key' || !cred.key) continue;
      const provider = key.substring('apikey:'.length);
      const envVar = providerEnvVars[provider];
      if (envVar && !process.env[envVar]) {
        process.env[envVar] = cred.key;
      }
    }
  }

  /**
   * Login to an OAuth provider.
   */
  async login(providerId: OAuthProviderId, callbacks: OAuthLoginCallbacks): Promise<void> {
    const provider = getOAuthProvider(providerId);
    if (!provider) {
      throw new Error(`Unknown OAuth provider: ${providerId}`);
    }

    const credentials = await provider.login(callbacks);
    this.set(providerId, { type: 'oauth', ...credentials });
  }

  /**
   * Logout from a provider.
   */
  logout(provider: string): void {
    this.remove(provider);
  }

  /**
   * Get API key for a provider, auto-refreshing OAuth tokens if needed.
   */
  async getApiKey(providerId: string): Promise<string | undefined> {
    const cred = this.data[providerId];

View on GitHub (pinned to 75dd419e61)

Solutions

1. Use one of the registered OAuthProviderId values exactly (check getOAuthProvider/registry for the list).
2. Fix typos/casing in the provider id string.
3. If using a custom provider, register it with the registry before calling login.
4. Verify the SDK version hasn't renamed provider ids; update calling code accordingly.

Example fix

// before
await storage.login('openai' as any, callbacks);
// after
await storage.login('openai-codex', callbacks); // exact registered provider id

const KNOWN = ['openai-codex', 'xai'] as const; // registered OAuthProviderId values
function isRegisteredProvider(id: string): id is typeof KNOWN[number] {
  return (KNOWN as readonly string[]).includes(id);
}
if (!isRegisteredProvider(providerId)) throw new Error(`Provider "${providerId}" is not registered`);

function isOAuthProviderId(id: string): id is OAuthProviderId {
  return getOAuthProvider(id as OAuthProviderId) !== undefined;
}

try {
  await storage.login(providerId, callbacks);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Unknown OAuth provider')) {
    console.error(`Provider "${providerId}" unavailable; valid ids: ${listProviderIds().join(', ')}`);
  }
}

When it happens

Trigger: Calling storage.login(providerId, callbacks) with a providerId string that is not one of the registered OAuthProviderId values (typo, wrong casing, or unregistered custom provider).

Common situations: Hardcoded provider string like 'openai' instead of the exact id (e.g. 'openai-codex'); dynamically loaded provider not registered before login; config file value not matching known ids; version change renaming an id.

Related errors

• Redirect URI is required for SSO login
• Google client ID is required. Provide it in the options or s
• Redirect URI is required for Google SSO. Set GOOGLE_REDIRECT
• No Slack installation found for agent "${agentId}"
• SlackProvider baseUrl not available during OAuth callback

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/8a547422e2d60891. Report an issue: GitHub.