Manifest unknown
The registry could not find the manifest matching the requested image name or version tag.
Usually happens because:
- ☑ Typo in requested image tag version
- ☑ The tag lacks an image for your CPU architecture
- ☑ Latest tag was never pushed to the registry
🔍 Quick Checklist:
What is Manifest unknown?
This error occurs when the registry finds the image repository you requested, but cannot locate the specific manifest associated with the tag you provided. In Docker, a manifest is a JSON file that defines the image layers, configuration, and architecture support. If you try to pull a tag that was never built or pushed, the registry throws this error.
Common Causes
- Non-existent version tag: Referencing a tag that does not exist in the repository (e.g. pulling a typo version tag).
- Platform/Architecture mismatch: The requested tag does not support the host CPU architecture (e.g. pulling arm64 only tags on amd64 machine).
- Incomplete multi-arch push: The manifest list was partially uploaded during build stages, resulting in missing index references.
| Cause | Frequency |
|---|---|
| Non-existent version tag spelling | ⭐⭐⭐⭐⭐ |
| Unsupported host CPU architecture | ⭐⭐⭐⭐ |
| Broken multi-arch manifest list | ⭐⭐ |
Common Mistakes
- Assuming the 'latest' tag always exists (Docker does not automatically generate a 'latest' tag; it must be pushed manually).
- Pulling ARM-only images on x86 servers without enabling QEMU emulation.
How to Fix
Docker Operations & Verification
Inspect the manifest structure from the remote registry to verify supported host platforms.
$ docker manifest inspect node:20-alpine
# Outputs JSON list of platform architectures (amd64, arm64, 386 etc.)Platform Specific Fixes
Forcing platform specifications on Linux hosts.
docker pull --platform linux/amd64 alpine:3.18Best Practices
- Always check your registry dashboards to confirm that target tags have been successfully uploaded.
- Utilize Docker Buildx to build and push multi-architecture manifest lists in one run.
Frequently Asked Questions (FAQ)
Q: What is an image manifest?
A manifest is a JSON metadata file describing the layers, size, platform, and architecture bindings of a container image.
Q: Why does 'latest' throw manifest unknown?
Because the repository owner did not push a tag explicitly named 'latest'. Docker does not automatically generate a 'latest' tag; it must be pushed manually.
Q: How do I inspect available tags?
You can use the registry HTTP API, or inspect the registry repository dashboard.
Q: How do I check local architectures?
Run 'docker info' or inspect client configurations to check CPU architecture configurations.