Azure Container Registry Error: Resolving 'Manifest Unknown' and Missing Tag Issues

Updated: 17 Jul, 2025 • 0 • min read

Table of Contents

Azure Container Registry (ACR) serves as a managed, private Docker registry service in Azure, designed for building, storing, and managing container images and related artifacts. It’s an indispensable component for any modern cloud-native application development, seamlessly integrating with Azure Kubernetes Service (AKS), Azure App Service, and other compute services. As the central repository for your container images, efficient and accurate management of images, particularly through proper tagging, is paramount for smooth deployment pipelines and operational stability. Understanding how ACR manages these artifacts and diagnosing common issues is crucial for maintaining robust CI/CD workflows.

Azure Container Registry Error

However, like any complex system, users may encounter errors during routine operations. One of the more perplexing, yet common, issues developers face is the “Manifest Unknown” error during a container image pull request. This error directly impacts the ability to deploy applications, halting development and production environments. This article delves into the specifics of this error, exploring its root causes, and providing comprehensive steps for diagnosis and resolution, along with best practices to prevent its recurrence.

Understanding the ‘Manifest Unknown’ Error¶

When attempting to pull a container image from Azure Container Registry, you might encounter an error message similar to the following:

Manifest for <container-registry-name>.azurecr.io/v2/<repository>/manifests/<tag> not found: manifest unknown: manifest tagged by “<tag>” is not found.

This message indicates that the specific container image manifest referenced by the provided tag could not be located within the specified repository of your Azure Container Registry. The “manifest” in this context refers to a JSON document that describes a container image. It includes crucial information such as the image’s configuration, the layers that compose the image, and sometimes references to other manifests for different architectures (known as a manifest list or “fat manifest”). Essentially, it’s the blueprint that tells the Docker daemon or container runtime how to construct and run the image.

The error explicitly points out that the tag you used, **<tag>**, does not correspond to any known manifest within the target repository. This can be misleading because while the manifest itself might exist, it’s the association with the specified tag that is missing or incorrect. This discrepancy can arise from various stages of the container image lifecycle, from image build and push to later management and cleanup operations.

Common Causes of the ‘Manifest Unknown’ Error¶

While the immediate symptom is a missing tag, the underlying reasons can vary. Diagnosing the precise cause is the first step towards an effective solution. Here are the most common scenarios leading to the “Manifest Unknown” error:

1. Typographical Errors and Case Sensitivity¶

The simplest explanation is often the correct one: a typo. Container image tags and repository names are case-sensitive in Azure Container Registry. A slight misspelling or incorrect casing in the docker pull command (or within your deployment manifest) will result in the requested tag not being found, even if it exists with the correct casing. Always double-check the exact spelling and casing of both the repository name and the image tag.

2. Image Not Successfully Pushed¶

An image might fail to push completely or correctly to the registry. Network interruptions, insufficient permissions during the push operation, or issues on the client-side Docker daemon could prevent the image layers and its manifest from being fully uploaded and registered. In such cases, while you might think the image is available, ACR never fully received it, leading to the “manifest unknown” error upon pull. It’s crucial to verify the success of the docker push command in your CI/CD pipelines.

3. Incorrect Repository or Registry¶

It’s possible that the image exists but in a different repository or even a different Azure Container Registry than the one specified in the pull command. Large organizations often manage multiple registries or numerous repositories within a single registry. Mistakenly referencing the wrong location will naturally result in the target tag not being found. Confirming the full registry URL and repository path is a vital preliminary step.

4. Tag Deletion or Overwriting¶

Tags can be intentionally or accidentally deleted, or they might be overwritten. If a CI/CD pipeline repeatedly pushes images using a mutable tag like latest without unique versioning, previous images associated with that tag become inaccessible once a new image takes its place. Furthermore, manual deletion of tags via the Azure portal or Azure CLI can remove the manifest association, making the image appear missing.

5. Azure Container Registry Retention Policies and Pruning¶

ACR offers features like retention policies that automatically delete older images, manifests, or tags to manage storage costs and maintain registry hygiene. If a retention policy is configured to delete images older than a certain duration or to retain only a specific number of latest tags, the image you are trying to pull might have been automatically purged. Understanding and configuring these policies thoughtfully is essential to prevent unexpected image removal.

6. Permissions Issues¶

While the error message specifically states “manifest unknown” rather than “access denied,” insufficient permissions can indirectly lead to this state. If the user or service principal attempting the pull operation lacks the necessary AcrPull role on the specific repository or registry, the registry might not even expose the existence of the manifest, leading to a perceived “not found” error. Ensure that the identity performing the pull has appropriate Role-Based Access Control (RBAC) permissions.

7. Multi-Architecture Image Discrepancies¶

When dealing with multi-architecture images (e.g., images for amd64 and arm64), a single tag might point to a “manifest list” that contains references to architecture-specific manifests. If the client attempting to pull (e.g., a Docker daemon) requests an architecture that is not available in the manifest list, or if the manifest list itself is malformed or incomplete, it could lead to a “manifest unknown” error for that specific architectural variant.

Comprehensive Solution Steps and Best Practices¶

Resolving the “Manifest Unknown” error involves verifying the existence of the tag and the image, then addressing any underlying issues. Here’s a structured approach:

1. Verify the Existence of the Tag and Repository¶

The most immediate action is to confirm whether the tag truly exists within the expected repository.

Using the Azure Portal:¶

The Azure portal provides a user-friendly interface to visually inspect your container registry contents.

Navigate to Container Registries: In the Azure portal, use the search bar at the top and type “Container registries”. Select Container registries from the search results.
Select Your Registry: From the list of container registries, click on the name of the specific registry that you are working with.
Browse Repositories: In the left-hand menu pane of your container registry, under the Services section, select Repositories. This will display a list of all repositories within your selected registry.
Inspect the Repository: Locate and select the name of the repository where you expect the image tag to reside. This will open a view showing all tags associated with that repository.
Check for the Tag: Carefully examine the list of tags within the repository. Verify if the tag in question is present and if its casing exactly matches what you are using in your pull command. You can also inspect details like the creation date to see if the image is recent or potentially old and subject to retention policies.

Using Azure CLI:¶

The Azure CLI offers powerful command-line tools for managing ACR, which can be particularly useful for scripting and automation.

List Tags in a Repository:
To list all tags within a specific repository and confirm the existence of your tag, use the az acr repository show-tags command:
```
az acr repository show-tags --name <my-registry> --repository <my-repository> --orderby time_desc --output table
```
Replace <my-registry> with your ACR name and <my-repository> with the name of the repository. The --orderby time_desc option is useful for seeing the most recently pushed tags first, and --output table provides a clear, tabular view.
Verify Repository Existence:
If you’re unsure about the repository name itself, you can list all repositories in your registry:
```
az acr repository list --name <my-registry> --output table
```
Inspect Manifests (Advanced):
For a deeper dive into the manifests themselves, you can use az acr repository show-manifests. This command lists all manifests (which are essentially image digests) associated with a repository, along with their tags.
```
az acr repository show-manifests --name <my-registry> --repository <my-repository> --output jsonc
```
This can help verify if a manifest exists but simply isn’t tagged correctly. Each manifest has a unique digest (SHA256 hash), which you can use to pull an image directly if the tag is missing: docker pull <my-registry>.azurecr.io/<my-repository>@sha256:<manifest-digest>.

2. Addressing Specific Causes¶

Once you’ve verified the tag’s existence (or lack thereof), you can take targeted action:

Correct Typos/Casing: If a typo was the issue, simply correct the tag or repository name in your pull command or deployment configuration.
Re-Push the Image: If the image wasn’t successfully pushed, re-run your build and push process. Ensure that the docker push command completes without errors. Verify the image and tag appear in the Azure portal or via CLI afterward.
Review CI/CD Pipelines: If your image management is automated, meticulously review your CI/CD pipeline configurations. Ensure that:
- Images are tagged consistently and uniquely (e.g., using Git commit SHAs or build numbers).
- The docker push command targets the correct registry and repository.
- Error handling for docker push failures is robust.
Understand Retention Policies: Check your registry’s retention policies under Services > Retention in the Azure portal. Adjust them if they are too aggressive and inadvertently deleting necessary images. Consider applying policies specifically to older, untagged manifests rather than actively used tags.
Check RBAC Permissions: Confirm that the identity pulling the image (user, service principal, or managed identity) has at least the AcrPull role assigned to the ACR instance or the specific repository. This can be checked under Access control (IAM) for the registry in the Azure portal.

3. Proactive Measures and Best Practices¶

Prevention is always better than cure. Adopting robust practices for image tagging and management can significantly reduce the likelihood of encountering the “Manifest Unknown” error.

Implement a Consistent Tagging Strategy:

Semantic Versioning: Use tags like v1.0.0, v1.0.1, v2.0.0. This provides clear versioning and immutability.
Immutable Tags: Avoid relying solely on mutable tags like latest for production deployments. While latest is convenient for development, it can be overwritten, making it difficult to reproduce builds or roll back. Always tag critical builds with unique, immutable tags.
Git SHA/Build Number: Incorporate the Git commit SHA or build pipeline run ID into your tags (e.g., feature-branch-abcd123). This ensures absolute uniqueness and traceability.

Tagging Strategy	Description	Pros	Cons
`latest`	Points to the most recently pushed image.	Convenient for development/testing of latest code.	Highly mutable; can lead to unpredictable deployments; difficult to rollback.
Semantic Versioning (`vX.Y.Z`)	Adheres to semantic versioning (Major.Minor.Patch).	Clear versioning, allows for reproducible builds, easy to track changes.	Requires disciplined version bumping; can lead to many tags over time.
Git Commit SHA / Build ID	Uses the full or truncated Git commit hash or pipeline build number.	Immutable, unique, highly traceable to source code, perfect for CI/CD.	Less human-readable; requires tools to map back to code version.
Feature Branch (`feature-xyz`)	For images built from specific feature branches.	Isolates feature development, good for testing.	Can proliferate quickly; needs cleanup.

Integrate with CI/CD Effectively:
Ensure your CI/CD pipelines are configured to:
- Build images with unique, descriptive tags.
- Push images to the correct ACR repository.
- Verify the success of the push operation before proceeding.
- Optionally, promote images through environments (e.g., from dev to qa to prod) by re-tagging or copying images within ACR using az acr repository copy.
Regularly Audit Your Registry:
Periodically review the contents of your ACR using the Azure portal or CLI. This helps identify untagged manifests that might be consuming space, or images that should have been deleted by policies but weren’t. Early detection of discrepancies can prevent issues.
Leverage ACR Webhooks:
ACR webhooks can notify external services about events like image pushes or deletions. This can be used to trigger automated validation or cleanup processes, further enhancing registry management.

Further Resources and Advanced Troubleshooting¶

Sometimes, even after basic checks, the issue persists. In such cases, deeper investigation might be necessary.

Checking ACR Diagnostic Logs¶

Azure Container Registry provides comprehensive diagnostic logs that can be sent to Azure Log Analytics, Storage Accounts, or Event Hubs. Configuring diagnostic settings for your ACR instance can provide invaluable insights into pull and push operations, authentication attempts, and other registry activities. By analyzing these logs, you might uncover specific errors or unauthorized access attempts that led to the manifest being unavailable.

Understanding Manifest Lists for Multi-Architecture Images¶

If you’re dealing with images that support multiple CPU architectures (e.g., x86 and ARM), ensure your build process correctly creates a manifest list. A common tool for this is docker manifest create and docker manifest annotate. If the manifest list is incomplete or incorrectly formed, clients might fail to find the correct architecture-specific manifest.

# Example: Creating a multi-arch manifest (concept only, requires specific image digests)
# docker manifest create myregistry/myimage:mytag \
#   myregistry/myimage:mytag-amd64 \
#   myregistry/myimage:mytag-arm64
#
# docker manifest annotate myregistry/myimage:mytag myregistry/myimage:mytag-arm64 --os linux --arch arm64
# docker manifest push myregistry/myimage:mytag

Visualizing ACR Flow with Mermaid Diagram¶

A typical CI/CD flow involving Azure Container Registry and its interaction with deployment environments can be visualized as follows:

mermaid graph TD A[Developer Commits Code] --> B(CI Pipeline Triggered); B --> C{Build Container Image}; C --> D[Tag Image]; D --> E(Push Image to Azure Container Registry); E -- Success --> F{Image Tagged & Stored}; E -- Failure --> G(Error: Manifest Unknown); F --> H[CD Pipeline Triggered]; H --> I(Pull Image from ACR); I -- Success --> J[Deploy Application]; I -- Failure --> K(Error: Manifest Unknown); K --> L[Troubleshoot Tag/Manifest Issue]; L --> M{Verify Tag Existence}; M -- Tag Found --> N[Check Permissions / Registry Status]; M -- Tag Not Found --> O[Re-push Image / Check Retention Policies]; N --> P[Resolve & Retry]; O --> P;

Quick Troubleshooting Tips (Instagram Style)¶

For quick, actionable advice, follow these tips:

[Instagram Post Placeholder]
Image: A vibrant infographic showing checkmarks and crosses next to “Tag Exists?” “Permissions Ok?” “Typo?”
Caption: Facing ‘Manifest Unknown’ in Azure Container Registry? Don’t panic! 🕵️‍♀️ Here are your quick checks:
1. Double-check your docker pull command for typos! Tags are case-sensitive.
2. Verify the tag in Azure Portal or CLI (az acr repository show-tags). Does it really exist?
3. Ensure your image was pushed successfully! Look for push errors in your CI/CD logs.
4. Confirm you’re pulling from the CORRECT repository/registry. Easy mistake!
5. Check your ACR retention policies. Was it automatically purged?

Conclusion¶

The ‘Manifest Unknown’ error in Azure Container Registry can be a frustrating roadblock, but it is almost always indicative of a straightforward issue: the requested image tag is simply not found where expected. By systematically verifying the existence of your tags through the Azure portal or CLI, understanding the various causes, and implementing robust image management and CI/CD practices, you can effectively diagnose and prevent this error. Adopting clear tagging strategies and proactively monitoring your registry health are key steps towards maintaining a smooth and reliable container deployment pipeline.

We hope this comprehensive guide assists you in resolving this common ACR error and strengthens your container image management practices. Do you have any other common ACR issues you’d like to see covered? Share your experiences and questions in the comments below!

Computacionvinchi