Fix Docker Push to a Missing ECR Repository

DEV Community

Docker push to ECR repository does not exist

Docker push to ECR repository does not exist means the registry accepted your credentials and then found nothing to push into, so create the repository first: Amazon ECR only makes one during a push when a repository creation template matches the name. The login is not the problem, which is why the fix is in your infrastructure rather than in your workflow credentials. ECR creates a repository during a push only when a creation template matches the name. Otherwise the repository has to exist before the push starts. What this error means The login step passes, the layers start uploading or fail immediately, and the push ends on a "name unknown" error that names the repository and the registry id. The registry id is your AWS account number and the host carries the region, so the message is telling you exactly where it looked. It is deterministic: the same push fails the same way until a repository exists at that name, in that account, in that region. We have not reproduced this one on a runner, because a real push needs AWS credentials and an account we are not going to put in a public page, so the log below is the shape ECR prints rather than a recorded run. Everything else on this page is quoted from the AWS documentation, read on 2026-09-20. ```The shape ECR prints on push (illustrative, not a recorded run) The push refers to repository [123456789012.dkr.ecr.us-east-1.amazonaws.com/api] name unknown: The repository with name 'api' does not exist in the registry with id '123456789012'

Common causes

The repository was never created

The first deploy of a new service, or a service renamed in the workflow and nowhere else. Everything up to the push works, which is what makes it confusing: the credentials are valid, the image built, and the registry is real. Only the repository is missing.

The push is pointed at the wrong region or account

A copied workflow keeps a region, a role change moves the account, or a matrix deploys to two regions from one reference. The repository exists, just not where the push looked. The registry id in the error is the account it actually reached.

A creation template exists and its prefix does not match

A template set up for prod covers repositories beginning with prod/ and nothing else, so a push to staging/api gets no repository and this error. In our experience this is the surprising one, because the team knows create-on-push is configured and does not know it is scoped by prefix.

The job can push but cannot create

A pipeline written to create the repository on demand fails at the create call instead, with an access error rather than this one, when its role carries only the documented push permissions. The AWS push policy grants the layer and image actions and the authorization token, not repository creation.

How to fix it

Create the repository before the first push

1. Create it once with aws ecr create-repository in the correct region, or in your infrastructure tool.
2. Confirm it from the job with aws ecr describe-repositories and the name.
3. Keep the name in one variable that both the tag and the create call read.

```Terminal
aws ecr create-repository --repository-name api --region us-east-1
aws ecr describe-repositories --repository-names api --region us-east-1 \
- -query "repositories[0].repositoryUri" --output text
Add a repository creation template if you want create-on-push Define the template with the prefix your services use and CREATE_ON_PUSH among its applied-for actions, so the first push of a new service makes the repository with the settings you chose. Use ROOT as the prefix to cover every repository that has no more specific template. aws ecr create-repository-creation-template \
- -prefix prod \
- -applied-for CREATE_ON_PUSH \
- -image-tag-mutability MUTABLE \
- -region us-east-1
Give the job the permission the fix needs The documented push policy covers uploading layers and putting an image. A job that creates reposit...

Powered by Readybot.io