How to fix 'manifest unknown' when pulling an image

Overview

The error manifest unknown appears when a registry cannot find the requested manifest by tag or digest. Common causes include mistyped tags, missing architectures, private image permissions, and case or namespace mismatches. This guide shows fast, practical checks and fixes.

Quickstart: fastest fixes

1. Verify the reference
   • Use a real tag: e.g., alpine:3.20 instead of alpine:latest (which may not exist).
   • Ensure repository path is correct and lowercase.
2. Authenticate (for private images)
   • docker login <registry>
3. Check platform
   • Pull with an explicit platform matching what exists: --platform=linux/amd64 or linux/arm64.
4. Pin by digest
   • Prefer image@sha256:... when available to avoid tag drift.
5. Inspect the manifest
   • Use docker manifest inspect to confirm the tag/digest exists and which platforms are available.

Minimal working example

This shows a known-good pull, a reproducer of the error, and the fix.

# Known-good pull (public, multi-arch tag)
docker pull alpine:3.20

# Inspect the manifest to confirm platforms
docker manifest inspect alpine:3.20 | head -n 20

# Reproduce: a non-existent tag
# Expect: manifest unknown
set +e
docker pull alpine:9.99 || true
set -e

# Fix: correct the tag and/or specify platform
# (Example for AMD64 hosts; change to linux/arm64 if needed)
docker pull --platform=linux/amd64 alpine:3.20

Step-by-step diagnosis

1. Confirm the repository and tag

   • Ensure the full name is correct: registry/namespace/name:tag.
   • OCI requires lowercase repository names. Convert to lowercase.
   • Example formats:
     • Docker Hub official: alpine:3.20
     • Docker Hub user: docker.io/youruser/app:1.2.3
     • GHCR: ghcr.io/org/app:1.2.3

2. Check if the tag or digest exists

   • Inspect the manifest remotely:

     docker manifest inspect alpine:3.20 >/dev/null && echo "exists"
     

   • If this reports an error, the tag truly does not exist or requires auth.

3. Authenticate if private

   docker login ghcr.io      # or your registry
   docker pull ghcr.io/org/app:1.2.3
   

4. Verify architecture/platform

   • Find your Docker platform:

     docker info --format '{{.OSType}}/{{.Architecture}}'
     

   • If the image lacks your platform, specify one that exists (emulation may apply):

     docker manifest inspect nginx:1.25 | grep -A2 platform
     docker pull --platform=linux/amd64 nginx:1.25
     

5. Pin a digest to avoid tag drift

   • If a tag was moved or deleted, pull by digest if you have it:

     docker pull alpine@sha256:<digest>
     

6. Distinguish errors

   • name unknown: repository path is wrong or repo doesn’t exist.
   • manifest unknown: repo exists, but the referenced tag/digest does not.

Common causes and fixes

Registry-specific notes

• Docker Hub
  • Official images omit the namespace (alpine:3.20). Other images require docker.io/user/repo:tag.
  • Anonymous pulls are rate-limited; authenticate to reduce errors.
• GHCR (GitHub Container Registry)
  • Requires ghcr.io prefix and proper scopes. Repositories are lowercase and often private by default.
• ECR/GAR/ACR
  • Fully qualify images (account/region endpoints). Ensure your auth helpers (e.g., aws ecr get-login-password) run before pulling.

Pitfalls to avoid

• Assuming latest exists. Many images do not publish latest; use explicit tags.
• Ignoring platform. Multi-arch images may omit your architecture; check with docker manifest inspect.
• Using CI credentials without pull scope. Ensure read:packages (GHCR) or equivalent permissions.
• Relying on tag mutability. Tags can be retagged or deleted; pin critical workloads to digests.
• Case sensitivity. Keep repo names lowercase to satisfy OCI rules across registries.

Performance notes

• Reduce repeated failing pulls
  • A loop that retries a non-existent tag wastes time and registry quota. Validate existence first with docker manifest inspect.
• Prefer digests in production
  • Pulling by digest avoids cache misses from tag retargeting and ensures layer reuse across deployments.
• Use a registry mirror or local cache
  • For CI fleets, configure a pull-through cache to minimize latency and rate-limit exposure.
• Consolidate platforms
  • Build/publish only the platforms you need to avoid bloated manifests and reduce client negotiation time.

Tiny FAQ

• Q: I can docker pull on my laptop, but CI fails with manifest unknown.

  • A: CI likely lacks auth or uses a different platform. Login in CI and set --platform to a supported architecture.

• Q: docker manifest inspect says no such manifest. Is the registry down?

  • A: Usually the tag/digest doesn’t exist or requires auth. Verify the reference and login to the registry.

• Q: Why does specifying --platform fix my pull?

  • A: The tag may only include certain architectures. By requesting a supported platform, the registry can return a valid manifest list entry.

• Q: Should I use latest?

  • A: Prefer explicit versions or digests. latest may not exist and can move, causing surprises.

Summary

manifest unknown indicates the registry cannot find the requested tag or digest. Verify the reference, authenticate, check platforms, and prefer digest pinning. Use docker manifest inspect to confirm availability before pulling and to quickly isolate tag problems from auth or architecture issues.