Troubleshoot Azure Container Registry delete operation issues

Summary

This article helps you troubleshoot Azure Container Registry (ACR) delete operation issues that occur when you delete images, artifacts, or repositories. Use it to resolve errors and free storage to maintain registry health and reduce costs.

Issue 1: Can't delete an empty repository

When you try to delete an empty repository from a container registry, you get an error message that resembles the following messages.

• Error when using the Azure portal:

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

• Error when using Azure CLI:

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

Solution

This error occurs because some orphaned metadata is left behind when you delete the images. To avoid this error, don't empty the repository. Instead, delete the entire repository. This process is more effective because it deletes all images in the repository, including all tags, unique layers, and manifests.

Add a dummy image before you delete the entire repository.

Issue 2: Can't delete a container registry associated with private endpoints

If an Azure container registry is associated with private endpoints, deleting the container registry fails. Before you can delete it, you must remove all private endpoints that are associated with it.

Solution

Use the Azure portal or the az acr private-endpoint-connection delete command. For more information, see Manage private endpoint connections.

Issue 3: Delete operation doesn't clear used storage

When you run the acr purge command in an ACR task to delete lots of images, the storage usage doesn't decrease.

In ACR, each image has its corresponding unique manifest and manifest digest. However, different images might share the same layers. See the following screenshot for an example.

To save storage space in ACR, the service stores only one copy of layers that multiple different manifests reference.

Based on the preceding screenshot, if you delete image B, the service cleans up the manifest and manifest digest. At the layer level, the service deletes only layer 4. The service keeps layers 1 and 2 in ACR storage because another manifest still references them. Therefore, the storage reduction is less than expected.

Issue 4: "The operation is disallowed" error when you delete an ACR repository

You receive the following error message when you try to delete an ACR repository.

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

Cause

This error occurs because a lock exists on your repository, manifest, or image layer. Run the following commands to check for locks.

1. Check whether there are any locks at the repository level.

   az acr repository show --name myregistry --repository myrepo
   

2. Check locks at the repository manifest digest level.

   
   az acr manifest list-metadata -registry myregistry -name myrepo      
   

3. Check locks at the repository image tag level.

   az acr repository show --name myregistry --image imagename:tag
   

The following example shows the output.

{
  "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 the writeEnabled attribute is set to false, the repository or image is locked against delete operations.

Solution

To resolve this issue, run the following commands to change writeEnabled to true:

1. Remove the lock at the repository level.

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

2. Remove the lock at the manifest level.

   az acr repository update --name myregistry --image myrepo@sha256:123456abcdefg --write-enabled true
   

3. Remove the lock at the image tag level.

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