How to fix Error: Error creating ECR Repository: RepositoryAlreadyExistsException in Terraform

TerraformINTERMEDIATEMEDIUMUpdated Dec 31, 2025· 104 views

This error occurs when Terraform attempts to create an AWS ECR repository that already exists. It happens due to state file mismatches or concurrent deployments trying to create the same repository name.

Quick fix

Fixes RepositoryAlreadyExistsException

aws ecr describe-repositories --repository-names your-repo-name
  1. Verify the repository exists in AWS
  2. Import the existing repository into Terraform state
  3. Handle count or for_each indexed resources
  4. Verify the import with terraform plan
terraform — error
aws ecr describe-repositories --repository-names your-repo-name
Error: Error creating ECR Repository: RepositoryAlreadyExistsException

What this error means

When you run `terraform apply`, the aws_ecr_repository resource attempts to create a new ECR repository, but AWS rejects the request because a repository with that name already exists in your registry. This typically occurs when there's a mismatch between your Terraform state file and actual AWS resources, or when multiple deployments or environments inadvertently target the same repository name.

Typical symptoms

  • Terraform apply fails with RepositoryAlreadyExistsException
  • Error message mentions a repository name that already exists in the registry
  • Plan shows creating a new repository, but apply fails
  • Repository is accessible in AWS Console but Terraform doesn't know about it

Common causes

  1. Repository was created manually via AWS Console or CLI and never imported into Terraform state
  2. State file loss or corruption caused Terraform to forget about an existing repository
  3. Multiple Terraform configurations or workspaces targeting the same repository name without coordination
  4. Previous Terraform apply created the repository but the state file wasn't updated correctly
  5. Shared repository name across different environments (dev, staging, prod) without unique naming strategy

How to fix "Error: Error creating ECR Repository: RepositoryAlreadyExistsException"

1Verify the repository exists in AWS

First, confirm the ECR repository actually exists in your AWS account:

bash
aws ecr describe-repositories --repository-names your-repo-name

If it returns repository details, it exists. Note the exact repository name for the next step.

2Import the existing repository into Terraform state

Use terraform import to register the existing repository with your Terraform state:

bash
terraform import aws_ecr_repository.my_repo your-repo-name

Replace aws_ecr_repository.my_repo with your resource identifier in Terraform and your-repo-name with the actual ECR repository name in AWS.

3Handle count or for_each indexed resources

If you're using count or for_each in your resource definition, adjust the import command:

For count:

bash
terraform import 'aws_ecr_repository.repo[0]' your-repo-name

For for_each:

bash
terraform import 'aws_ecr_repository.repo["mykey"]' your-repo-name
4Verify the import with terraform plan

After importing, run terraform plan to ensure Terraform now recognizes the repository and won't try to recreate it:

bash
terraform plan

You should see no changes to the ECR repository resource. If there are still changes, review the resource configuration to ensure it matches the actual AWS resource.

5Use unique repository names per environment

To prevent this error in the future, ensure each environment has uniquely named repositories. Use Terraform variables and naming conventions:

hcl
resource "aws_ecr_repository" "app" {
  name = "${var.environment}-${var.app_name}"
}

For example: dev-myapp, staging-myapp, prod-myapp.

6Enable lifecycle rules for safer repository management

Configure lifecycle rules and policies to manage repositories consistently:

hcl
resource "aws_ecr_repository" "app" {
  name                 = "my-app"
  image_tag_mutability = "MUTABLE"

  image_scanning_configuration {
    scan_on_push = true
  }

  lifecycle {
    prevent_destroy = true
  }
}

The prevent_destroy flag helps prevent accidental deletions.

Advanced notes

State file consistency: The root cause often involves AWS API eventual consistency. When Terraform creates an ECR repository, it sends CreateRepository followed by DescribeRepositories, but the DescribeRepositories call may temporarily fail even though the repository was created. This can leave Terraform unaware the resource exists. Always run terraform import for existing repositories rather than modifying your configuration to work around the error. For multi-environment setups, consider using Terraform workspaces or separate backend configurations per environment to avoid state conflicts.

Frequently asked questions

What does "RepositoryAlreadyExistsException" mean?
When you run terraform apply, the aws_ecr_repository resource attempts to create a new ECR repository, but AWS rejects the request because a repository with that name already exists in your registry. This typically occurs when there's a mismatch between your Terraform state file and actual AWS resources, or when multiple deployments or environments inadvertently target the same repository name.
How do I fix "RepositoryAlreadyExistsException"?
This error occurs when Terraform attempts to create an AWS ECR repository that already exists. It happens due to state file mismatches or concurrent deployments trying to create the same repository name.
What causes "RepositoryAlreadyExistsException"?
Repository was created manually via AWS Console or CLI and never imported into Terraform state State file loss or corruption caused Terraform to forget about an existing repository Multiple Terraform configurations or workspaces targeting the same repository name without coordination
Is the "RepositoryAlreadyExistsException" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading