--- cuppy_hub: azure cuppy_path: reference/azure-identity/errors.md cuppy_section: docs cuppy_doc: ZTRJ-MHNR cuppy_doc_uuid: 06a5aacc-5b30-4369-8b7b-2a7c940b1ecb cuppy_permalink: https://cuppy.io/azure/d/ZTRJ-MHNR cuppy_version: 1 cuppy_updated: 2026-10-23T16:16:52.575Z cuppy_canonical: https://cuppy.io/azure/docs/reference/azure-identity/errors cuppy_mcp: https://cuppy.io/mcp cuppy_body_sha256: 5181d55255d1a9f65aff241a6f850cd753be0f39f6e6914f9116039ee8ab7026 # cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks. --- # Azure Identity SDK errors (TypeScript) **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 = . 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 '' 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 --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//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 ` 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 --resource-group ` | | `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 --resource-group ` | 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 "" --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. --- You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 107 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/azure/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.