How to fix Error: Error creating Container Registry: AlreadyExists in Terraform

TerraformINTERMEDIATEMEDIUMUpdated Dec 31, 2025· 100 views

This error occurs when attempting to create an Azure Container Registry (ACR) that already exists in Azure. The registry name must be globally unique across all Azure subscriptions. This typically happens when the resource was previously created outside Terraform or when Terraform state is lost. The fix involves checking if the resource exists, importing it into state, using unique names, or properly managing Terraform backend state.

Quick fix

Fixes AlreadyExists

az acr show --resource-group <resource-group-name> --name <registry-name>
  1. Check if the container registry already exists in Azure
  2. Import the existing resource into Terraform state
  3. Use unique naming for container registries
  4. Configure remote Terraform backend state (for CI/CD)
terraform — error
az acr show --resource-group <resource-group-name> --name <registry-name>
Error: Error creating Container Registry: AlreadyExists

What this error means

Azure Container Registry names must be globally unique across all of Azure. When Terraform attempts to create a registry with a name that already exists (either in your subscription or any other), Azure returns the AlreadyExists error. This typically indicates either: (1) the resource was created previously but Terraform state was lost, (2) the resource exists in another subscription or tenant, (3) Terraform state management is misconfigured in CI/CD pipelines, or (4) the chosen name is already taken by another user.

Typical symptoms

  • Terraform apply fails with 'Error: Error creating Container Registry: AlreadyExists'
  • The error occurs immediately without timeout
  • Same configuration works locally but fails in CI/CD pipelines
  • Resource appears in Azure Portal but not in Terraform state
  • Subsequent Terraform runs fail with the same error
  • No change in resource but Terraform still tries to create it

Common causes

  1. Container Registry name is globally unique across all Azure subscriptions and the chosen name is already taken
  2. Resource was created outside Terraform (via Portal, Azure CLI, or another tool) and lost from Terraform state
  3. Terraform backend state is not properly configured, causing state loss in CI/CD environments
  4. Resource was created in a previous Terraform run but state file was deleted or not persisted
  5. Multiple Terraform configurations trying to create the same resource with hardcoded names
  6. Name conflicts when deploying to different subscriptions or environments with identical resource names

How to fix "Error: Error creating Container Registry: AlreadyExists"

1Check if the container registry already exists in Azure

Run the Azure CLI command to verify if the ACR with the desired name exists:

bash
az acr show --resource-group <resource-group-name> --name <registry-name>

If the resource exists and you want to manage it with Terraform, proceed to import it into state. If it doesn't exist, the issue is likely a Terraform state problem.

2Import the existing resource into Terraform state

If the ACR already exists in Azure, import it into your Terraform state using the import command:

bash
terraform import azurerm_container_registry.acr /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ContainerRegistry/registries/<registry-name>

Replace the placeholders with your actual values. You can get the subscription ID with az account show --query id. After importing, Terraform will track the existing resource and won't try to recreate it.

3Use unique naming for container registries

To avoid name conflicts entirely, use a random suffix in your registry name:

hcl
resource "random_string" "acr_suffix" {
  length  = 8
  special = false
  upper   = false
}

resource "azurerm_container_registry" "acr" {
  name                = "myacr${random_string.acr_suffix.result}"
  resource_group_name = azurerm_resource_group.rg.name
  location            = azurerm_resource_group.rg.location
  sku                 = "Basic"
  admin_enabled       = false
}

This ensures a globally unique name by combining your prefix with random characters.

4Configure remote Terraform backend state (for CI/CD)

If deploying from CI/CD pipelines, ensure Terraform state is persisted in a remote backend. Add this configuration to your main.tf:

hcl
terraform {
  backend "azurerm" {
    resource_group_name  = "terraform-state-rg"
    storage_account_name = "tfstatestg"
    container_name       = "tfstate"
    key                  = "prod.terraform.tfstate"
  }
}

Initialize the backend with terraform init. This prevents state loss between pipeline runs and ensures all team members work with the same state.

5Delete and recreate the resource (if safe)

If you want Terraform to fully manage the resource and the ACR contains no critical data, you can delete it and let Terraform recreate it:

bash
# Remove from Azure
az acr delete --resource-group <resource-group-name> --name <registry-name>

# Clear Terraform state if needed
terraform state rm azurerm_container_registry.acr

# Re-run Terraform
terraform apply

WARNING: Only do this if the ACR is empty or the data is not needed. This operation is destructive and cannot be undone.

6Verify backend state is persisted between runs

Before running Terraform in CI/CD, verify that:

1. Backend storage account and container exist
2. Pipeline has read/write access to the backend storage
3. terraform init is called before every terraform plan or terraform apply
4. State file isn't manually deleted or modified

Run terraform state list to verify Terraform can see existing resources in state. If empty, state is not properly persisted.

Advanced notes

ACR names are globally unique within the entire Azure ecosystem, making them prone to naming conflicts. For multi-environment deployments, consider using deployment slot names or random suffixes. If you're managing ACRs across multiple subscriptions, use Azure Data Source to reference existing registries instead of creating new ones. For enterprise scenarios, implement naming conventions using prefixes (company code + environment + random) and validate names before applying. The AlreadyExists error might appear during provider initialization if other checks fail; ensure your azurerm provider version is current and compatible with your Terraform version. Some organizations use Azure Policy to enforce naming standards and prevent duplicate resource names at the API level.

Frequently asked questions

What does "AlreadyExists" mean?
Azure Container Registry names must be globally unique across all of Azure. When Terraform attempts to create a registry with a name that already exists (either in your subscription or any other), Azure returns the AlreadyExists error. This typically indicates either: (1) the resource was created previously but Terraform state was lost, (2) the resource exists in another subscription or tenant, (3) Terraform state management is misconfigured in CI/CD pipelines, or (4) the chosen name is already taken by another user.
How do I fix "AlreadyExists"?
This error occurs when attempting to create an Azure Container Registry (ACR) that already exists in Azure. The registry name must be globally unique across all Azure subscriptions. This typically happens when the resource was previously created outside Terraform or when Terraform state is lost. The fix involves checking if the resource exists, importing it into state, using unique names, or properly managing Terraform backend state.
What causes "AlreadyExists"?
Container Registry name is globally unique across all Azure subscriptions and the chosen name is already taken Resource was created outside Terraform (via Portal, Azure CLI, or another tool) and lost from Terraform state Terraform backend state is not properly configured, causing state loss in CI/CD environments
Is the "AlreadyExists" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading