🚨 Docker Error Guide: 'name unknown: repository name not known to registry' — Wrong Repo Path

Overview

The registry returns this error when it cannot find the repository name in the image reference you pushed or pulled. It appears most often during docker push, and sometimes on docker pull:

name unknown: repository name not known to registry

The daemon usually wraps it with the reference it tried:

The push refers to repository [registry.example.com/team/myapp]
denied: requested access to the resource is denied
name unknown: repository name not known to registry

This is a naming/existence problem: the registry received a valid request but has no repository matching the path in your tag. It is not a network timeout or a disk error.

Symptoms

• docker push registry.example.com/team/myapp:1.4.2 fails with name unknown.
• The same image pushes successfully under a different repository path.
• Pulls of a repository that “should exist” fail because the name or namespace is misspelled.
• On registries that do not auto-create repositories, the first push to a brand-new name fails until the repo is created.
• The error sometimes appears alongside denied: requested access to the resource is denied when the path is both wrong and unauthorized.

Common Root Causes

• Repository was never created — some registries (Amazon ECR, Harbor with auto-create off, GitLab in certain modes) require the repo to exist before the first push.
• Missing or wrong namespace/project — pushing to myapp instead of team/myapp, or the wrong organization/project prefix.
• Typo in the repository path — a misspelled name, wrong case, or an extra/missing path segment.
• Registry host omitted — pushing myapp:1.4.2 without the registry prefix sends it to Docker Hub, where that name does not exist under your account.
• Wrong account or project scope — authenticated to one account but the repo lives under another.
• Registry not tagged into the reference — building with a bare name and forgetting to docker tag it with the full registry path.

Diagnostic Workflow

Confirm the exact reference you are pushing — the tag string is the whole story:

docker image ls | grep myapp
docker image inspect myapp:1.4.2 --format '{{json .RepoTags}}'

Verify you are logged into the right registry and account:

docker login registry.example.com
cat ~/.docker/config.json | grep -A1 auths

Query the registry catalog (v2 API) to see which repositories actually exist:

curl -s https://registry.example.com/v2/_catalog | tr ',' '\n'
curl -s https://registry.example.com/v2/team/myapp/tags/list

For Amazon ECR, list repositories to confirm the target exists before pushing:

aws ecr describe-repositories --query 'repositories[].repositoryName'

Re-tag with the full, correct path and retry the push:

docker tag myapp:1.4.2 registry.example.com/team/myapp:1.4.2
docker push registry.example.com/team/myapp:1.4.2

Example Root Cause Analysis

An engineer builds locally as myapp:1.4.2 and pushes with docker push registry.example.com/myapp:1.4.2, which fails: name unknown: repository name not known to registry. The registry is a Harbor instance where every image must live inside a project, and there is no top-level myapp project. Checking the catalog confirms the expected path:

curl -s https://registry.example.com/v2/_catalog | tr ',' '\n'
# "team/api"
# "team/web"

Every real repository is nested under team/. The push failed because myapp has no project namespace. Re-tagging with the correct project prefix resolves it:

docker tag myapp:1.4.2 registry.example.com/team/myapp:1.4.2
docker push registry.example.com/team/myapp:1.4.2

For an ECR registry, the equivalent fix is creating the repository first, since ECR does not auto-create:

aws ecr create-repository --repository-name team/myapp

Prevention Best Practices

• Always tag images with the full registry/namespace/name:tag reference; never rely on bare names for pushes.
• Standardize a naming convention (registry.example.com/<team>/<service>) and enforce it in CI push scripts.
• For registries without auto-create, provision repositories as part of infrastructure-as-code (Terraform ECR/Harbor resources) before the first pipeline run.
• Validate the target repository exists in CI with a catalog or describe-repositories check before docker push.
• Keep docker login and the push target pointed at the same registry host and account.
• Fail fast in build scripts if the IMAGE variable is missing the registry prefix.

Quick Command Reference

# See the exact reference on your image
docker image inspect myapp:1.4.2 --format '{{json .RepoTags}}'

# List repositories the registry actually has
curl -s https://registry.example.com/v2/_catalog

# List existing ECR repos
aws ecr describe-repositories --query 'repositories[].repositoryName'

# Create an ECR repo before first push
aws ecr create-repository --repository-name team/myapp

# Re-tag with the full path and push
docker tag myapp:1.4.2 registry.example.com/team/myapp:1.4.2
docker push registry.example.com/team/myapp:1.4.2

Conclusion

name unknown: repository name not known to registry means the registry received your request but has no repository matching the path in your image reference. The fix is almost always in the tag: confirm the full registry/namespace/name:tag, verify the repository exists (creating it first on registries that require it), and re-tag before pushing. Standardizing naming and provisioning repositories ahead of time in CI eliminates the error entirely. For more registry fixes, see the Docker guides.