manifest unknown" Docker push error fix

TL;DR

Docker's "manifest unknown" on push means the registry does not recognize the repository name or the tag you are pushing to, usually because the image is not tagged with the full registry path or you lack permission to create that repository. Retag the image with the complete [registry]/[repo]:[tag] name, confirm you are logged in, then push again.

Error / query

"manifest unknown" Docker push error fix

Use this skill when

• docker push fails with manifest unknown: manifest unknown or name unknown
• The push fails right after a successful docker build
• Pushing to a new repository name in the registry for the first time
• CI pushes fail while local pushes to the same registry work

Not for this skill when

• docker pull fails with manifest unknown (the image genuinely does not exist remotely; check the tag)
• The error is unauthorized or denied (auth problem, different fix)
• The push fails mid-upload with network errors (connectivity, not naming)
• You are debugging registry storage or garbage collection (server-side, not the push command)

Steps

Step 1: Inspect how the image is currently tagged

docker images | grep -i [image-name]

Expected: the REPOSITORY column shows the full name. If it is just [image] with no registry host, the push is going to the wrong place (default Docker Hub) and the registry answers "manifest unknown".

Step 2: Retag with the full registry path

docker tag [image]:[tag] [registry-host]/[repo]/[image]:[tag]
docker images | grep [registry-host]

Expected: the new tag appears with the complete path. Every segment (host, namespace/repo, tag) must match what the registry expects.

Step 3: Confirm you are logged in to that registry

docker login [registry-host]

Expected: Login Succeeded. An expired or missing login can surface as manifest/name errors on registries that hide "repository not found" behind auth.

Step 4: Push the fully qualified tag

docker push [registry-host]/[repo]/[image]:[tag]

Expected: layer upload progress ending in [tag]: digest: sha256:... size: .... That digest line is the success signal.

Step 5: Verify the manifest exists in the registry

docker buildx imagetools inspect [registry-host]/[repo]/[image]:[tag] | head -20

Expected: manifest details print without errors. If this fails after a successful push, suspect registry replication lag or a read/write permission split.

Variant phrasings

"docker push name unknown repository does not exist"

The repo path is wrong or your credentials cannot see it. Steps 2-3 cover both.

"manifest unknown pushing to ECR/GCR/ACR"

Cloud registries need the exact repository URI format and the repo may need to exist first (ECR does not auto-create by default). Create the repository, then push.

"denied: requested access to the resource is denied on push"

Auth or permission, not naming. Check the login identity has push rights to that repository.

Why it happens

docker push addresses the registry purely by the tag string. A short tag like myapp:latest resolves against the default registry and library namespace, so pushing to a private registry without the full path targets a repository that does not exist there. Registries answer unknown repositories with "manifest unknown" or "name unknown" rather than a friendlier message.

Edge cases and pitfalls

• Multi-arch images pushed per-arch without a manifest list show manifest unknown on pull of the combined tag; push with docker buildx --push to create the list.
• Some registries are case-sensitive and reject uppercase in repository names; keep names lowercase.
• CI credential helpers can silently use stale tokens; re-login in the pipeline if pushes worked before and stopped.
• Pushing to a tag that a retention policy just garbage-collected can behave oddly; check registry retention rules.
• A proxy or mirror in front of the registry can return manifest unknown for uncached paths; push directly to the registry host to test.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_K-qA8wrJvzsAXnh02WAGlg