Troubleshoot registry login

  • Article

This article helps you troubleshoot problems you might encounter when logging into an Azure container registry.

Symptoms

May include one or more of the following:

  • Unable to login to registry using docker login, az acr login, or both
  • Unable to login to registry and you receive error unauthorized: authentication required or unauthorized: Application not registered with AAD
  • Unable to login to registry and you receive Azure CLI error Could not connect to the registry login server
  • Unable to push or pull images and you receive Docker error unauthorized: authentication required
  • Unable to access a registry using az acr login and you receive error CONNECTIVITY_REFRESH_TOKEN_ERROR. Access to registry was denied. Response code: 403. Unable to get admin user credentials with message: Admin user is disabled. Unable to authenticate using AAD or admin login credentials.
  • Unable to access registry from Azure Kubernetes Service, Azure DevOps, or another Azure service
  • Unable to access registry and you receive error Error response from daemon: login attempt failed with status: 403 Forbidden - See Troubleshoot network issues with registry
  • Unable to access or view registry settings in Azure portal or manage registry using the Azure CLI

Causes

  • Docker isn't configured properly in your environment - solution
  • The registry doesn't exist or the name is incorrect - solution
  • The registry credentials aren't valid - solution
  • The registry public access is disabled. Public network access rules on the registry prevent access - solution
  • The credentials aren't authorized for push, pull, or Azure Resource Manager operations - solution
  • The credentials are expired - solution

Further diagnosis

Run the az acr check-health command to get more information about the health of the registry environment and optionally access to a target registry. For example, diagnose Docker configuration errors or Microsoft Entra login problems.

See Check the health of an Azure container registry for command examples. If errors are reported, review the error reference and the following sections for recommended solutions.

Follow the instructions from the AKS support doc if you fail to pull images from ACR to the AKS cluster.

Note

Some authentication or authorization errors can also occur if there are firewall or network configurations that prevent registry access. See Troubleshoot network issues with registry.

Potential solutions

Check Docker configuration

Most Azure Container Registry authentication flows require a local Docker installation so you can authenticate with your registry for operations such as pushing and pulling images. Confirm that the Docker CLI client and daemon (Docker Engine) are running in your environment. You need Docker client version 18.03 or later.

Related links:

Specify correct registry name

When using docker login, provide the full login server name of the registry, such as myregistry.azurecr.cn. Ensure that you use only lowercase letters. Example:

docker login myregistry.azurecr.cn

When using az acr login with a Microsoft Entra identity, first sign in to the Azure CLI, and then specify the Azure resource name of the registry. The resource name is the name provided when the registry was created, such as myregistry (without a domain suffix). Example:

az acr login --name myregistry

Related links:

Confirm credentials to access registry

Check the validity of the credentials you use for your scenario, or were provided to you by a registry owner. Some possible issues:

  • If using an Active Directory service principal, ensure you use the correct credentials in the Active Directory tenant:
    • User name - service principal application ID (also called client ID)
    • Password - service principal password (also called client secret)
  • If using an Azure service such as Azure Kubernetes Service or Azure DevOps to access the registry, confirm the registry configuration for your service.
  • If you ran az acr login with the --expose-token option, which enables registry login without using the Docker daemon, ensure that you authenticate with the username 00000000-0000-0000-0000-000000000000.
  • If your registry is configured for anonymous pull access, existing Docker credentials stored from a previous Docker login can prevent anonymous access. Run docker logout before attempting an anonymous pull operation on the registry.

Related links:

Confirm credentials are authorized to access registry

Confirm the registry permissions that are associated with the credentials, such as the AcrPull Azure role to pull images from the registry, or the AcrPush role to push images.

Access to a registry in the portal or registry management using the Azure CLI requires at least the Reader role or equivalent permissions to perform Azure Resource Manager operations.

If your permissions recently changed to allow registry access though the portal, you might need to try an incognito or private session in your browser to avoid any stale browser cache or cookies.

You or a registry owner must have sufficient privileges in the subscription to add or remove role assignments.

Related links:

Check that credentials aren't expired

Tokens and Active Directory credentials may expire after defined periods, preventing registry access. To enable access, credentials might need to be reset or regenerated.

  • If using an individual AD identity, a managed identity, or service principal for registry login, the AD token expires after 3 hours. Log in again to the registry.
  • If using an AD service principal with an expired client secret, a subscription owner or account administrator needs to reset credentials or generate a new service principal.
  • If using a repository-scoped token, a registry owner might need to reset a password or generate a new token.

Related links:

Advanced troubleshooting

If collection of resource logs is enabled in the registry, review the ContainerRegistryLoginEvents log. This log stores authentication events and status, including the incoming identity and IP address. Query the log for registry authentication failures.

Related links:

Next steps

If you don't resolve your problem here, see the following options.