Azure Identity SDK errors (TypeScript)
Look up an @azure/identity error by class and message — AggregateAuthenticationError, AuthenticationRequiredError, CredentialUnavailableError, "DefaultAzureCredential failed to retrieve a token from the included credentials", environment, certificate, managed identity, workload identity, Azure CLI and azd messages, and a 401 or 403 RestError after a successful sign-in — with the cause, the check and the fix.
markdownreferencev1ZTRJ-MHNRstage: operatetrust: officialservice: azure-identityinterface: sdkChainedTokenCredential authentication failedEnvironmentCredential is unavailable. No underlying credential could be usedAttempted to use the IMDS endpoint but it is not availableManagedIdentityCredential Network unreachableAzure CLI could not be foundCredentialUnavailableErrorAuthenticationRequiredErrorAggregateAuthenticationErrorAuthenticationErrorDefaultAzureCredential failed to retrieve a token from the included credentialsEnvironment variables aren't fully configuredManagedIdentityCredential authentication unavailableThe requested identity hasn't been assigned to this resourceNo response received from the managed identity endpointPlease run 'az login' to set up accountAzure CLI not installedWorkloadIdentityCredential authentication unavailableendpoints_resolution_errorProvide either a PEM certificateRestError 403AZURE_TOKEN_CREDENTIALS invalid value
The messages below are the ones @azure/identity 4.14.0 throws (read from its code), with the older wording from Microsoft's troubleshooting guide where it differs: search for either.
Read the class first. CredentialUnavailableError means a credential couldn't even try (missing configuration): in a chain, the next one is tried. AuthenticationRequiredError (and AuthenticationError, with errorResponse) means it tried and Microsoft Entra refused: the message carries the AADSTS code, the failing credential and the correlation ID, so look the code up in reference/entra/errors.md. AggregateAuthenticationError comes from a chain and holds every credential's error in errors[].
First check for any row: setLogLevel("info") (or AZURE_LOG_LEVEL=info) prints which credentials the chain tried and which one answered.
Chain and environment
| Message | Cause → fix | Check |
|---|---|---|
AggregateAuthenticationError: ChainedTokenCredential authentication failed. (guide: DefaultAzureCredential failed to retrieve a token from the included credentials.) | Every credential in the chain was unavailable. Configure the one you mean (sign in with az login, give the host a managed identity, set the environment variables) | The info log lists each credential's own reason |
EnvironmentCredential is unavailable. No underlying credential could be used. (guide: Environment variables aren't fully configured.) | EnvironmentCredential found an incomplete set. A secret needs AZURE_CLIENT_ID, AZURE_TENANT_ID and AZURE_CLIENT_SECRET; a certificate needs AZURE_CLIENT_CERTIFICATE_PATH instead of the secret. Set them before the process starts | Print which of those variables are set (names only) |
Invalid value for AZURE_TOKEN_CREDENTIALS = <value>. Valid values are 'prod' or 'dev' or any of these credentials - … | Not dev, prod or a credential class name (case-insensitive) | echo $AZURE_TOKEN_CREDENTIALS |
Required environment variable '<name>' for DefaultAzureCredential is not set or empty. (plain Error, thrown by the constructor) | A variable named in requiredEnvVars is missing. This is the fail-fast working as intended | The named variables |
RestError 401 or 403 from a service client | Sign-in succeeded but as the wrong identity, or the right one lacks a role at that scope (or the role was granted minutes ago) | Log with allowLoggingAccountIdentifiers: true, then az role assignment list --assignee <object-id> --all |
Service principal and certificate
| Message | Cause → fix | Check |
|---|---|---|
endpoints_resolution_error … Could not retrieve endpoints. Check your authority and verify the .well-known/openid-configuration endpoint returns the required endpoints. | Wrong tenantId, or no network path to login.microsoftonline.com | curl -s https://login.microsoftonline.com/<tenant>/v2.0/.well-known/openid-configuration from the same host |
ClientCertificateCredential: Provide either a PEM certificate in string form, or the path to that certificate in the filesystem. | No certificate given. The JavaScript library takes PEM only | The value passed or AZURE_CLIENT_CERTIFICATE_PATH |
The file at the specified path doesn't contain a PEM-encoded certificate. | A pfx or a PEM without the private key | head -1 <file> shows -----BEGIN and the file contains a PRIVATE KEY block |
AADSTS7000215, AADSTS7000222, AADSTS700016 inside the message | Bad secret, expired secret, app not in tenant | reference/entra/errors.md |
Managed identity
| Message | Cause → fix | Check |
|---|---|---|
ManagedIdentityCredential: Authentication failed. Message … with The requested identity hasn't been assigned to this resource. | IMDS answered 400: the user-assigned client ID asked for isn't attached to this VM, or the system-assigned identity is off. Often AZURE_CLIENT_ID was set for something else (reference/azure-identity/credential-chain.md) | az vm identity show --name <vm> --resource-group <rg> |
The request failed due to a gateway error. | IMDS returned 502 or 504: a proxy sits in front of 169.254.169.254. Proxies aren't supported; bypass it for that address | echo $HTTP_PROXY $HTTPS_PROXY $NO_PROXY |
Attempted to use the IMDS endpoint, but it is not available., ManagedIdentityCredential: Network unreachable. Message: … (guide: No response received from the managed identity endpoint.) | No managed identity endpoint here (code isn't running on Azure, or the identity isn't enabled), or a timeout | Is this host an Azure resource with an identity enabled? |
Multiple attempts failed to obtain a token from the managed identity endpoint. | Retries exhausted; read the inner errors | Info log |
ManagedIdentityCredential authentication unavailable. (App Service, Functions) | The platform's identity variables aren't present: no identity enabled on the app | az webapp identity show --name <app> --resource-group <rg> |
More managed identity failures, including the 24-hour token cache: reference/managed-identity/errors.md.
Developer and CI credentials
| Message | Cause → fix | Check |
|---|---|---|
Azure CLI could not be found. Please visit https://aka.ms/azure-cli for installation instructions … | az isn't on PATH for this process | which az in the same shell |
Please run 'az login' from a command prompt to authenticate before using this credential. | No session, or it expired | az account show, then az account get-access-token --scope https://management.azure.com/.default |
Subscription "…" contains invalid characters. If this is the name of a subscription, use its ID instead | Pass the subscription ID | az account show --name "<name>" --query id |
Azure Developer CLI couldn't be found. / Please run 'azd auth login' from a command prompt to authenticate before using this credential. | Same, for azd | azd auth login |
WorkloadIdentityCredential: is unavailable. … (guide: WorkloadIdentityCredential authentication unavailable. The workload options are not fully configured.) | Needs client ID, tenant ID and token file path (AZURE_FEDERATED_TOKEN_FILE) | Print those three (AKS: child hub) |
AADSTS900023: Specified tenant identifier … is neither a valid DNS name, nor a valid external domain. (AzurePipelinesCredential) | Wrong tenant ID for the service connection | The service connection's tenant |
When none of these fits
Build a ChainedTokenCredential with only the credential you expect, so its own error surfaces instead of the aggregate. Keep the correlation ID from the message for support.