Docker "manifest unknown" / "manifest not found" - Fix Missing Tags

By Daniel Zoghalchali·Latchkey

The registry has the repository but not the specific tag or digest you asked for. The image name resolves; the reference does not.

What this error means

A pull fails with manifest unknown or manifest for <repo>:<tag> not found. The repository clearly exists (other tags pull fine), but this exact reference does not.

Error response from daemon: manifest for myorg/api:relese-1 not found:
manifest unknown: manifest unknown

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 tag was never pushed or was a typo

A misspelled tag (relese-1), or a tag your pipeline assumed exists but a previous job failed to push, leaves nothing for the registry to return.

The tag or digest was deleted or retag­ged

Registry retention policies, manual cleanup, or a moved tag can remove the manifest you cached a reference to.

Architecture/variant not present in the manifest list

For a multi-arch tag, the manifest list may exist but lack an entry for your platform, so the resolved per-arch manifest is "unknown".

How to fix it

List the tags that actually exist

Inspect the registry to confirm the reference before pulling.

docker buildx imagetools inspect myorg/api:1.4.2
# or query tags via the registry API / your provider's CLI

Pin to an immutable digest

Reference images by digest so a moved or deleted tag cannot silently break the pull.

docker pull myorg/api@sha256:9f2c...

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

• Verify the push succeeded before downstream jobs pull the tag.
• Pin production references by digest, not by a mutable tag.
• Align retention policies with how long your pipelines reference old tags.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation