Fixing Azure Container Registry Deletion Errors: A Practical Troubleshooting Guide

Updated: 27 Aug, 2025 • 0 • min read

Table of Contents

Azure Container Registry (ACR) serves as a robust private registry service, essential for the lifecycle management of container images and associated artifacts. It provides a secure and scalable platform for building, storing, and deploying containerized applications. Maintaining the health and efficiency of your ACR instance often necessitates regular cleanup operations, including the deletion of outdated images, artifacts, and entire repositories. These maintenance tasks are crucial for optimizing storage costs and ensuring the registry remains streamlined and performant.

Despite the straightforward nature of deletion operations, users occasionally encounter challenges that prevent successful removal of resources. Understanding the underlying causes of these errors is key to effective troubleshooting and maintaining an efficient container registry. This comprehensive guide delves into common deletion issues experienced with Azure Container Registry and provides actionable solutions to resolve them, ensuring your registry remains in optimal condition.

Understanding Azure Container Registry Fundamentals¶

Before diving into specific troubleshooting scenarios, it’s beneficial to grasp the core components and hierarchy within Azure Container Registry. An ACR instance hosts multiple repositories, each designed to store a collection of related container images. Each image is uniquely identified by a manifest digest and can have one or more tags, which are human-readable labels pointing to a specific manifest. Crucially, images are composed of layers, which represent changes in the container’s filesystem. ACR intelligently stores these layers, allowing multiple images to share common layers, thereby optimizing storage space. This layered architecture plays a significant role in understanding how storage is managed and how deletion operations impact actual disk usage.

Key ACR Concepts:
- Registry: The top-level service instance.
- Repository: A collection of related images, e.g., my-app.
- Manifest: A JSON document describing an image, including its layers and configuration, identified by a digest (SHA256 hash).
- Tag: A human-readable label pointing to a specific manifest, e.g., my-app:latest.
- Layer: A component of an image, often shared between multiple images to save space.

ACR Architecture Overview

Issue 1: Can’t Delete an Empty Repository¶

A common frustration arises when attempting to delete an apparently empty repository, only to be met with an error message indicating the repository is “not known to registry.” This often occurs even after you’ve diligently removed all images and tags from within that repository, leading to confusion about its persistent existence.

Error Messages Encountered:

When using the Azure portal, the error typically appears as:

{'code':'NAME_UNKNOWN','message':'repository name not known to registry','detail':{'name':'mailhog'}}

Through the Azure CLI, a similar message is generated:

2024-05-08 12:14:04.261355 Error: repository name not known to registry. Correlation ID: aaaa0000-bb11-2222-33cc-444444dddddd

Cause of the Error:

This error primarily stems from orphaned metadata that remains within the registry even after all visible images and tags have been deleted. While the visible references to container images are gone, some internal pointers or metadata related to the repository might persist, making it appear “empty” to the user but not fully expunged from the registry’s internal index. When you attempt to delete a repository that is already technically empty but has this lingering metadata, the system struggles to locate a valid “repository” entity to perform the deletion on, resulting in the “not known” error.

Solution: Delete the Entire Repository, Not Just Its Contents

The most effective way to circumvent this issue is to avoid emptying the repository piecemeal. Instead, aim to delete the entire repository as a single operation. This approach ensures that all associated images, tags, unique layers, and manifests are thoroughly removed, preventing the creation of orphaned metadata.

To successfully delete the entire repository, particularly if it’s currently showing as “empty” but generating errors, follow these steps:

Add a Dummy Image: Temporarily push a lightweight, dummy image into the problematic repository. This re-establishes a valid, referenceable item within the repository, allowing the system to recognize it as a concrete entity once more.
```
# Example: Push a minimal busybox image to your repository
az acr login --name myregistry
docker tag busybox myregistry.azurecr.io/myrepo/dummy:latest
docker push myregistry.azurecr.io/myrepo/dummy:latest
```
Replace myregistry with your ACR name and myrepo with the name of the repository you wish to delete.
Delete the Entire Repository: Once the dummy image is pushed, the repository is no longer “empty” in a problematic sense. You can now proceed to delete the entire repository using the Azure CLI. This command will recursively remove all contents, including the dummy image, and importantly, the repository itself, along with any lingering metadata.
```
az acr repository delete --name myregistry --repository myrepo --yes
```
The --yes flag confirms the deletion without requiring an additional prompt. This ensures a clean removal of the repository and all its associated artifacts, resolving the “not known” error.

By following this process, you effectively bypass the metadata issue and perform a complete, clean deletion of the repository, optimizing your registry’s health.

Issue 2: Can’t Delete a Container Registry Associated with Private Endpoints¶

Azure Container Registry instances are often secured using private endpoints to enhance network security and ensure data access only over a private network. While this provides robust security, it introduces a dependency that can complicate deletion operations. If an ACR instance is configured with private endpoints, attempting to delete the registry directly will invariably fail.

Cause of the Error:

The inability to delete an ACR associated with private endpoints stems from Azure’s resource dependency model. Private endpoints create network interfaces within your virtual network that are specifically linked to the ACR resource. These links are considered critical dependencies. Azure’s Resource Manager prevents the deletion of a parent resource (the ACR) if dependent child resources (the private endpoint connections) still exist. This protective mechanism prevents accidental breakage of network connectivity and ensures resource integrity.

Solution: Remove All Private Endpoints First

To successfully delete an Azure Container Registry that has private endpoint associations, you must first dismantle these connections. This involves identifying and then removing each private endpoint that links to your ACR instance.

Steps to Remove Private Endpoints:

You can achieve this through either the Azure portal or the Azure CLI.

Using the Azure Portal:

Navigate to your ACR: In the Azure portal, search for and select your Azure Container Registry.
Access Networking Settings: In the ACR’s left-hand menu, under Settings, select Networking.
Manage Private Endpoint Connections: Go to the Private endpoints tab. Here, you will see a list of all private endpoint connections associated with your registry.
Delete Each Connection: For each private endpoint connection listed, select it, and then click on the Delete option. Confirm the deletion when prompted.
Verify Removal: Ensure all private endpoint connections are successfully removed before attempting to delete the ACR.

Using the Azure CLI:

List Private Endpoint Connections: First, identify all private endpoint connections linked to your ACR.
```
az acr private-endpoint-connection list --registry-name myregistry --query "[].name" --output tsv
```
Replace myregistry with the name of your Azure Container Registry. This command will output a list of private endpoint connection names.
Delete Each Connection: Iterate through the list of connection names and delete each one individually using the az acr private-endpoint-connection delete command.
```
# Example for deleting a single connection
az acr private-endpoint-connection delete --registry-name myregistry --name myPrivateEndpointConnectionName
```
You will need to run this command for every private endpoint connection identified in the previous step.

Once all associated private endpoints have been successfully removed, you can proceed to delete the Azure Container Registry without encountering dependency errors. This methodical approach ensures that all related resources are properly unlinked, allowing for a clean and successful deletion of the registry.

ACR Private Endpoint Diagram

Issue 3: Delete Operation Doesn’t Clear Used Storage¶

A common misconception among users is that deleting images from Azure Container Registry will immediately result in a significant reduction in reported storage usage. However, when users run commands like acr purge as part of their cleanup routines, they often observe that the total storage consumed by their ACR instance does not decrease as much as expected.

Cause: Shared Layers and Content-Addressable Storage

The primary reason for this behavior lies in ACR’s intelligent storage architecture, specifically its use of content-addressable storage and layer sharing. In ACR, each container image is associated with a unique manifest and manifest digest. However, the underlying layers that constitute these images can be shared across multiple different manifests.

Consider the following illustrative scenario:

```mermaid
graph LR
subgraph Registry
A[Image A: Manifest A] → L1(Layer 1);
A → L2(Layer 2);
A → L3(Layer 3);

    B[Image B: Manifest B] --> L1;
    B --> L2;
    B --> L4(Layer 4);
end

```

In this diagram:
- Image A is composed of Layer 1, Layer 2, and Layer 3.
- Image B is composed of Layer 1, Layer 2, and Layer 4.

Notice that Layer 1 and Layer 2 are shared between both Image A and Image B. ACR stores these shared layers only once to conserve storage space.

Impact of Deletion on Storage:

If you were to delete Image B in this scenario:

The manifest and manifest digest for Image B would be cleaned up.
At the layer level, only Layer 4 would be deleted from ACR storage. This is because Layer 4 is only referenced by Image B.
Layer 1 and Layer 2 would remain in ACR storage. This is crucial because Image A still references them. Until all images referencing Layer 1 and Layer 2 are deleted, these layers will persist.

Therefore, the actual storage reduction after deleting Image B would only reflect the size of Layer 4, not the combined size of all layers associated with Image B. This leads to the observed discrepancy where the storage usage decreases less than anticipated.

Table: Impact of Image Deletion on Shared Layers

Image	Manifest	Layers	Status After Deleting Image B	Storage Impact
Image A	Manifest A	L1, L2, L3	Remains	L1, L2, L3 continue to occupy space
Image B	Manifest B	L1, L2, L4	Deleted	Manifest B removed
Layers
L1		Referenced by A, B	Remains	Still referenced by A
L2		Referenced by A, B	Remains	Still referenced by A
L3		Referenced by A	Remains	Still referenced by A
L4		Referenced by B	Deleted	No longer referenced by any image

Managing ACR Storage Effectively:

To effectively manage storage and see significant reductions, you must:

Understand Dependencies: Recognize that true storage reduction only occurs when layers become unreferenced by any remaining manifests.
Target Full Repositories/Manifests: Use az acr repository delete for entire repositories, or az acr manifest delete for specific manifests, ensuring the --force flag is used if you want to also delete unreferenced layers.
Use acr purge with Caution: While acr purge is excellent for automated cleanup, remember its impact on storage is tied to the unique layers being removed. Use parameters like --keep and --before to precisely control which images are targeted. Always perform a dry-run (--dry-run) first to understand what will be deleted.
Monitor Usage: Regularly check your ACR storage usage in the Azure portal or via CLI commands (az acr show --name myregistry --query "currentDataCenterStorageInGb") to track trends and identify large storage consumers.

By grasping the concept of layer sharing, you can set realistic expectations for storage reduction and implement more effective strategies for ACR maintenance and cost optimization.

Issue 4: “The operation is disallowed” Error When Deleting ACR Repository¶

Encountering a “The operation is disallowed on this registry, repository or image” error message during an ACR deletion attempt can be puzzling, especially when you have the necessary permissions. This error is a strong indicator that an explicit lock or protection mechanism is in place, preventing the intended operation.

Error Message Example:

The operation is disallowed on this registry, repository or image.

Cause of the Error: Resource Locks

This error primarily occurs because a resource lock has been applied at the repository, manifest, or even the image layer level within your Azure Container Registry. These locks are a protective feature designed to prevent accidental deletion or modification of critical resources. While Azure offers broad resource locks (e.g., CanNotDelete and ReadOnly locks at the resource group or individual resource level), ACR also has its own internal attribute-based locking mechanism, specifically deleteEnabled and writeEnabled flags that can be set to false. When writeEnabled (which often implies deleteEnabled in this context) is set to false for a particular ACR entity, any attempt to delete or modify it will be blocked, resulting in the “disallowed” error.

How to Check for Locks:

You can identify if a lock is present and causing the issue by querying the attributes of your ACR resources using the Azure CLI.

Check for Locks at the Repository Level:
This command retrieves metadata for an entire repository.
```
az acr repository show --name myregistry --repository myrepo
```
Check Locks at the Repository Manifest Digest Level:
This command lists metadata for manifests within a repository, allowing you to inspect individual manifests.
```
az acr manifest list-metadata --registry myregistry --name myrepo
```
Check Locks at the Repository Image Tag Level:
This command provides metadata specific to an image identified by its tag.
```
az acr repository show --name myregistry --image imagename:tag
```

Example of Output Indicating a Lock:

When you run these commands, look for the changeableAttributes section in the JSON output. An output similar to this indicates a lock is preventing deletion:

{
  "changeableAttributes": {
    "deleteEnabled": false,
    "listEnabled": true,
    "readEnabled": true,
    "writeEnabled": false
  },
  "createdTime": "2024-08-20T15:22:51.0355721Z",
  "imageName": "myImage_0a1c809cc2eb596028fcf7a68e498e09",
  "lastUpdateTime": "2024-08-20T15:23:01.2739647Z",
  "manifestCount": 1,
  "registry": "myACR.azurecr.io",
  "tagCount": 2
}

If deleteEnabled or writeEnabled (which implicitly governs deletion for many operations) is set to false, it confirms that a lock is active, preventing deletion.

Solution: Remove the Lock by Setting writeEnabled to true

To resolve this issue, you need to explicitly change the writeEnabled attribute to true for the specific repository, manifest, or image tag that is locked. This will lift the protection and allow deletion.

Commands to Remove Locks:

Remove the Lock at the Repository Level:

az acr repository update --name myregistry --repository myrepo --write-enabled true

Remove the Lock at the Manifest Level:
You’ll need the specific manifest digest (e.g., sha256:123456abcdefg) for this command.
```
az acr repository update --name myregistry --image myrepo@sha256:123456abcdefg --write-enabled true
```

Remove the Lock at the Image Tag Level:

az acr repository update --name myregistry --image hello-world:latest --write-enabled true

Important Considerations:

Permissions: Ensure the Azure identity you are using has sufficient permissions (e.g., AcrPush or AcrDelete roles, or a custom role with Microsoft.ContainerRegistry/registries/repositories/write or delete permissions) to modify these attributes.
Caution: Removing locks should be done with care. Resource locks are typically put in place to protect critical resources from accidental changes. Only remove them when you are absolutely certain about the deletion and understand the implications.
Reapply Locks: After performing the necessary deletion, consider if the lock should be reapplied to prevent future unintended operations, especially for production-critical images or repositories.

By systematically identifying and then removing these specific ACR-level locks, you can regain control over your registry’s resources and successfully perform deletion operations.

Video Walkthrough: Troubleshooting and Removing ACR Locks

For a step-by-step visual guide on how to identify and resolve “The operation is disallowed” errors in Azure Container Registry by managing repository locks, watch this detailed walkthrough:

This video provides a practical demonstration of using Azure CLI commands to inspect and update ACR repository attributes to enable deletion.

Proactive Maintenance and Best Practices for ACR¶

Effective management of Azure Container Registry extends beyond reactive troubleshooting; it encompasses proactive maintenance and adherence to best practices. By integrating these strategies into your routine, you can significantly reduce the likelihood of encountering deletion errors and ensure your registry remains optimized for performance and cost.

1. Implement a Tagging Strategy:
Develop and enforce a clear tagging strategy for your container images. Tags should indicate image stability (e.g., latest, dev, prod), versioning (e.g., v1.0, v1.1), or build information. This makes it easier to identify and manage images, reducing the chance of mistakenly deleting critical ones.

2. Automate Image Retention Policies:
Leverage ACR’s built-in features for managing image lifecycles. Implement retention policies to automatically delete old, untagged, or specific-aged images. This prevents excessive storage growth and reduces the need for manual cleanup. For instance, you can configure ACR tasks to run acr purge periodically.

3. Understand and Manage Resource Locks:
Be intentional about where and why you apply resource locks. If you use Azure-level resource locks (CanNotDelete, ReadOnly), understand their scope and impact on ACR operations. For ACR’s internal writeEnabled attributes, use them judiciously on critical images or repositories to prevent accidental changes, but remember to remove them when legitimate deletion is required.

4. Regular Monitoring of Storage and Health:
Consistently monitor your ACR’s storage usage, repository count, and overall health. Azure Monitor provides metrics that can help you track storage consumption, identify growth trends, and proactively address potential issues before they escalate into critical problems. Early detection allows for timely cleanup and optimization.

5. Educate Your Team:
Ensure that all team members interacting with ACR are aware of its architecture, deletion nuances (especially layer sharing), and established cleanup procedures. A well-informed team is less likely to cause accidental issues or struggle with common operational tasks.

6. Utilize Dry-Run Operations:
Before executing any large-scale deletion commands, especially acr purge, always use the --dry-run flag. This allows you to preview which resources would be affected without actually performing the deletion, providing a critical safety net.

7. Implement Role-Based Access Control (RBAC):
Apply the principle of least privilege when assigning permissions to ACR. Grant users and service principals only the necessary roles (e.g., AcrPull, AcrPush, AcrDelete) required for their tasks. This minimizes the risk of unauthorized or accidental deletions.

By integrating these best practices, organizations can foster a healthier, more manageable Azure Container Registry environment, reducing operational overhead and ensuring the smooth deployment and management of containerized applications.

Conclusion¶

Managing Azure Container Registry effectively is fundamental to a robust containerization strategy. Encountering deletion errors can be frustrating, but by understanding the common pitfalls—such as orphaned metadata in empty repositories, dependencies on private endpoints, the nuances of shared layers affecting storage reduction, and the presence of resource locks—you can approach these issues systematically. This guide has provided practical, actionable solutions for each of these scenarios, empowering you to maintain a clean, cost-efficient, and secure container registry.

Proactive maintenance, informed decision-making, and a thorough understanding of ACR’s architecture are your strongest tools in preventing future issues. By adopting the best practices outlined, you can ensure your ACR operations are smooth and efficient, allowing your team to focus on building and deploying innovative containerized applications with confidence.

Do you have other ACR deletion challenges or tips you’d like to share? Please feel free to leave your comments and insights below. Your experiences help the entire community improve their ACR management strategies.

Computacionvinchi