Edit

Share via

Troubleshoot artifact cache issues in Azure Container Registry

  • Article

Learn how to solve the most common problems for a registry enabled with the artifact cache feature by identifying symptoms, causes, and potential solutions.

Cached images don't appear in a live repository

If cached images don't show up in your repository in Azure Container Registry (ACR), first verify that the repository path is correct:

  • The login server for Docker Hub is docker.io.
  • The login server for Microsoft Artifact Registry is mcr.microsoft.com.

The Azure portal autofills these fields for you. However, many Docker repositories begin with library/ in their path. For example, in-order to cache the hello-world repository, the correct Repository Path is docker.io/library/hello-world.

Unhealthy credentials

Credentials are a set of Azure Key Vault secrets that operate as a username and password for private repositories. Unhealthy credentials can occur when these secrets are no longer valid. In the Azure portal, you can select the credentials to edit and apply changes.

Verify that secrets in Azure Key Vault are valid, and that access to the Azure Key Vault is assigned.

To assign access to Azure Key Vault, run the following command:

az keyvault set-policy --name myKeyVaultName --object-id myObjID --secret-permissions get

For more information, see Key Vaults and Assigning access to Azure Key Vault.

Unable to create a cache rule

If you're unable to create a cache rule, you may have hit the cache rule limit, or your rule might have a conflict with an existing rule.

Cache rule limit issues

You may face issues while creating a cache rule if you exceed the limit of 1,000 cache rules.

If you hit this limit, delete any cache rules that are no longer needed.

Unable to create cache rule using a wildcard

If a cache rule you're trying to create conflicts with an existing rule, you see an error message explaining there's already a cache rule with a wildcard for the specified target repository.

To resolve this issue, follow these steps:

  1. Identify which existing cache rule is causing the conflict. Look for an existing rule that uses a wildcard (*) for the target repository.
  2. Delete the conflicting cache rule that overlaps with the source repository and wildcard.
  3. Create a new cache rule with the desired wildcard and target repository.
  4. Double-check your cache configuration to ensure that the new rule is correctly applied and there are no other conflicting rules.

For more information about wildcards and potential conflicts, see Wildcard support for artifact cache in Azure Container Registry.

Supported upstream repositories

Be sure your upstream repository is supported. For more information, see Upstream support.

Next steps

  • Learn how to use wildcards to match multiple paths within the container image registry.
  • Learn more about artifact cache.