Docker Push to ECR "repository does not exist" - Create the Repo First

By Daniel Zoghalchali·Latchkey

Amazon ECR rejected the push because the target repository does not exist. Unlike some registries, ECR does not create repositories on first push unless you explicitly enable it, so the repo must exist beforehand.

What this error means

A docker push <acct>.dkr.ecr.<region>.amazonaws.com/<repo>:<tag> fails with name unknown: The repository with name "api" does not exist in the registry. Login succeeded; the repository is just not there yet.

name unknown: The repository with name 'api' does not exist in the registry
with id '123456789012'

Diagnose it: separate auth from naming from rate limits

Registry errors look alike and have unrelated causes. Work out which of the three you have before changing credentials, because a malformed image reference produces an error that reads like an authentication failure.

# 1. is the reference even valid? (lowercase, no spaces, valid tag)
docker image inspect "$IMAGE" 2>&1 | head -2

# 2. are you authenticated to the right registry?
cat ~/.docker/config.json | grep -o '"[^"]*\.[^"]*"' | head

# 3. are you rate limited? (Docker Hub anonymous pulls)
curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimit-preview/test:pull" \
  | grep -o '"token"' >/dev/null && echo "token ok"

Common causes

The ECR repository was never created

ECR requires the repository to exist before a push. A first deploy of a new service hits this until the repo is created via console, CLI, or Terraform.

Wrong region or account in the registry URL

A repository that exists in one region/account is "not found" when the push targets a different region or account id.

How to fix it

Create the ECR repository before pushing

Create it with the CLI (or Terraform) in the correct region, then push.

aws ecr create-repository --repository-name api --region us-east-1
docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/api:1.4.2

Verify the registry URL’s region and account

Confirm the account id and region in the image reference match where the repo lives.

aws ecr describe-repositories --repository-names api --region us-east-1

Authenticate in the job, not in the image

- uses: docker/login-action@v3
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}

# GHCR needs this on the job or the push is rejected as unauthorised
permissions:
  contents: read
  packages: write

How to prevent it

• Create ECR repositories as part of infrastructure provisioning.
• Keep the account id and region in the registry URL consistent with the repo.
• Fail the pipeline early if the target ECR repo is missing.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation