mastra-ai/mastra · error · MastraError

AZURE_ENTRA_ID_TOKEN_ERROR

AZURE_ENTRA_ID_TOKEN_ERROR

Error message

Failed to get Entra ID token for Azure OpenAI gateway

What it means

The gateway is configured for Entra ID authentication, but credential.getToken(scope) returned null/undefined or a token with an empty token field. This means Azure AD refused or failed to issue an access token for the requested scope. It is thrown as a MastraError with the AZURE_ENTRA_ID_TOKEN_ERROR id.

Source

Thrown at packages/core/src/llm/model/gateways/azure.ts:508

      return token.token;
    } finally {
      this.entraIdTokenRequests.delete(cacheKey);
    }
  }

  private async fetchEntraIdToken(scope: string, cacheKey: string): Promise<CachedToken> {
    if (this.config.authentication?.type !== 'entraId') {
      throw new MastraError({
        id: 'AZURE_ENTRA_ID_AUTH_NOT_CONFIGURED',
        domain: 'LLM',
        category: 'UNKNOWN',
        text: 'Entra ID authentication is not configured for Azure OpenAI gateway',
      });
    }

    const accessToken = await this.config.authentication.credential.getToken(scope);
    if (!accessToken?.token) {
      throw new MastraError({
        id: 'AZURE_ENTRA_ID_TOKEN_ERROR',
        domain: 'LLM',
        category: 'UNKNOWN',
        text: 'Failed to get Entra ID token for Azure OpenAI gateway',
      });
    }

    const token = {
      token: accessToken.token,
      expiresAt: accessToken.expiresOnTimestamp
        ? Math.floor(accessToken.expiresOnTimestamp / 1000)
        : Math.floor(Date.now() / 1000) + 300,
    };

    await this.tokenCache.set(cacheKey, token);

    return token;
  }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Verify the credential chain works: run az login locally or enable the managed identity in your hosting environment.
2. Grant the identity access to the Azure OpenAI resource (e.g. 'Cognitive Services OpenAI User' role).
3. Confirm the scope is the correct Azure AD scope for your resource (cognitiveservices scope).
4. Wrap the credential with ChainedTokenCredential to add fallbacks (e.g. AzureCliCredential then DefaultAzureCredential).

Example fix

// before
const cred = new DefaultAzureCredential();
const token = await cred.getToken('https://cognitiveservices.azure.com/.default'); // null locally without login
// after
import { ChainedTokenCredential, DefaultAzureCredential, AzureCliCredential } from '@azure/identity';
await (new ChainedTokenCredential(new DefaultAzureCredential(), new AzureCliCredential())).getToken('https://cognitiveservices.azure.com/.default');
// and ensure 'az login' was run / managed identity is enabled

const probe = await credential.getToken('https://cognitiveservices.azure.com/.default');
if (!probe?.token) throw new Error('Credential cannot obtain a token for the Azure OpenAI scope — fix identity/roles before use');

try {
  await gw.token(scope);
} catch (e) {
  if (e.id === 'AZURE_ENTRA_ID_TOKEN_ERROR') {
    console.error('Token acquisition failed: check az login / managed identity / role assignments');
    // optionally rethrow after alerting
  }
  throw e;
}

When it happens

Trigger: fetchEntraIdToken() calls this.config.authentication.credential.getToken(scope); the result lacks a usable token — e.g. DefaultAzureCredential has no valid identity, managed identity disabled, service principal lacks consent, or the scope string is wrong.

Common situations: Running locally without az login while using DefaultAzureCredential; managed identity not enabled on the App Service/VM; service principal without role assignment to the Azure OpenAI resource; misconfigured tenant/subscription.

Related errors

• AZURE_AD_TOKEN_ERROR
• AZURE_ENTRA_ID_AUTH_NOT_CONFIGURED
• Repository access did not include a bearer token for the Fac
• AZURE_MANAGEMENT_CREDENTIALS_MISSING
• ${errorData.message || 'Invalid email or password'}

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