Docker "tag does not exist in registry" in CI

A pull names a repository plus a tag; if that tag does not exist in the registry, the registry returns "manifest unknown". In CI this is usually a typo, a tag that a previous job was supposed to push but did not, or a deleted/retention-expired tag.

What this error means

A docker pull myorg/app:somefeature fails with manifest for myorg/app:somefeature not found: manifest unknown even though the repository exists.

Error response from daemon: manifest for myorg/app:1.4.2-rc not found: manifest unknown: manifest unknown

Common causes

The tag was never pushed

A downstream job pulls a tag a build job failed to push, or pushed under a different name.

A typo or wrong tag computation

A mismatched tag derived from a branch/sha that does not match what was pushed.

The tag was deleted or expired

A registry retention policy or manual cleanup removed the tag.

How to fix it

Confirm the tag exists before pulling

1. List the tags in the repository and pull one that is actually present.

docker buildx imagetools inspect myorg/app:1.4.2-rc || \
  echo "tag missing in registry"

Make the producing job push the tag

1. Ensure the build/push job ran and pushed the exact tag the consumer expects.
2. Use the same tag expression in both jobs.

TAG="myorg/app:${GITHUB_SHA}"
docker buildx build --push -t "$TAG" .
# consumer uses the identical TAG

How to prevent it

• Compute the push and pull tag from one shared expression.
• Gate consumers on the producer job succeeding so the tag always exists first.

Related guides