{"record":{"id":"ee4ae7e725a2f93a","repo":"mastra-ai/mastra","slug":"azure-entra-id-token-error","errorCode":"AZURE_ENTRA_ID_TOKEN_ERROR","errorMessage":"Failed to get Entra ID token for Azure OpenAI gateway","messagePattern":"Failed to get Entra ID token for Azure OpenAI gateway","errorType":"exception","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/llm/model/gateways/azure.ts","lineNumber":508,"sourceCode":"      return token.token;\n    } finally {\n      this.entraIdTokenRequests.delete(cacheKey);\n    }\n  }\n\n  private async fetchEntraIdToken(scope: string, cacheKey: string): Promise<CachedToken> {\n    if (this.config.authentication?.type !== 'entraId') {\n      throw new MastraError({\n        id: 'AZURE_ENTRA_ID_AUTH_NOT_CONFIGURED',\n        domain: 'LLM',\n        category: 'UNKNOWN',\n        text: 'Entra ID authentication is not configured for Azure OpenAI gateway',\n      });\n    }\n\n    const accessToken = await this.config.authentication.credential.getToken(scope);\n    if (!accessToken?.token) {\n      throw new MastraError({\n        id: 'AZURE_ENTRA_ID_TOKEN_ERROR',\n        domain: 'LLM',\n        category: 'UNKNOWN',\n        text: 'Failed to get Entra ID token for Azure OpenAI gateway',\n      });\n    }\n\n    const token = {\n      token: accessToken.token,\n      expiresAt: accessToken.expiresOnTimestamp\n        ? Math.floor(accessToken.expiresOnTimestamp / 1000)\n        : Math.floor(Date.now() / 1000) + 300,\n    };\n\n    await this.tokenCache.set(cacheKey, token);\n\n    return token;\n  }","sourceCodeStart":490,"sourceCodeEnd":526,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/llm/model/gateways/azure.ts#L490-L526","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the credential chain works: run az login locally or enable the managed identity in your hosting environment.","Grant the identity access to the Azure OpenAI resource (e.g. 'Cognitive Services OpenAI User' role).","Confirm the scope is the correct Azure AD scope for your resource (cognitiveservices scope).","Wrap the credential with ChainedTokenCredential to add fallbacks (e.g. AzureCliCredential then DefaultAzureCredential)."],"exampleFix":"// before\nconst cred = new DefaultAzureCredential();\nconst token = await cred.getToken('https://cognitiveservices.azure.com/.default'); // null locally without login\n// after\nimport { ChainedTokenCredential, DefaultAzureCredential, AzureCliCredential } from '@azure/identity';\nawait (new ChainedTokenCredential(new DefaultAzureCredential(), new AzureCliCredential())).getToken('https://cognitiveservices.azure.com/.default');\n// and ensure 'az login' was run / managed identity is enabled","handlingStrategy":"retry","validationCode":"const probe = await credential.getToken('https://cognitiveservices.azure.com/.default');\nif (!probe?.token) throw new Error('Credential cannot obtain a token for the Azure OpenAI scope — fix identity/roles before use');","typeGuard":null,"tryCatchPattern":"try {\n  await gw.token(scope);\n} catch (e) {\n  if (e.id === 'AZURE_ENTRA_ID_TOKEN_ERROR') {\n    console.error('Token acquisition failed: check az login / managed identity / role assignments');\n    // optionally rethrow after alerting\n  }\n  throw e;\n}","preventionTips":["Run az login locally; enable managed identity in hosted environments.","Grant the identity 'Cognitive Services OpenAI User' on the resource.","Use ChainedTokenCredential for resilient fallbacks.","Verify the scope URL matches your resource's Azure AD scope."],"tags":["azure","entra-id","authentication","token"],"backgroundTag":"jwt-token-acquisition-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}