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

> Fix Docker push to Amazon ECR "name unknown: The repository ... does not exist in the registry" in CI - ECR does not auto-create repositories on push by default.

Source: https://latchkey.dev/learn/docker/docker-ecr-repository-does-not-exist-create  
Updated: 2026-06-25

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.

## 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.

```Terminal
# 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"
```

> Docker Hub rate-limits anonymous pulls by IP, and CI runners share IPs. A pull that works on your laptop and fails in CI with no config change is usually this, not credentials.

## Authenticate in the job, not in the image

```.github/workflows/ci.yml
- 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
```

## FAQ

### What causes Docker push to ECR "repository does not exist"?

There are 2 common causes: the ecr repository was never created and wrong region or account in the registry url. ECR requires the repository to exist before a push.

### How do I fix Docker push to ECR "repository does not exist"?

There are 2 fixes depending on which cause you have: create the ecr repository before pushing and verify the registry url’s region and account. Work through them in order, since the first is the most common.

### What does Docker push to ECR "repository does not exist" actually mean?

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.

### How do I stop Docker push to ECR "repository does not exist" happening again?

Create ECR repositories as part of infrastructure provisioning. The prevention section lists 3 changes that keep it from recurring.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt