Fix docker-manifest-not-found: Manifest for image not found when pulling from registry

The docker-manifest-not-found error is a common issue encountered when attempting to pull a Docker image from a registry. It signifies that the Docker daemon was unable to locate the image manifest, which is a crucial JSON document describing the image’s layers, configuration, and architecture, for the specified image name and tag. This problem typically prevents the successful download and subsequent use of the Docker image, halting deployment or development workflows. Understanding its root causes and systematic troubleshooting steps is essential for maintaining smooth container operations.

1. Symptoms: Clear description of indicators and shell output.

When encountering the docker-manifest-not-found error, the most prominent symptom is the failure of a docker pull or docker run command. The command will terminate with an error message indicating that the manifest for a specific image and tag could not be found. This usually occurs immediately after initiating the pull request to the Docker registry.

Typical shell output will look similar to this:

$ docker pull myregistry/myimage:nonexistent-tag
Error response from daemon: manifest for myregistry/myimage:nonexistent-tag not found: manifest unknown: manifest unknown

Or, if attempting to run a container from an image that isn’t locally present and cannot be pulled:

$ docker run myregistry/anotherimage:badtag echo "Hello"
Unable to find image 'myregistry/anotherimage:badtag' locally
docker: Error response from daemon: manifest for myregistry/anotherimage:badtag not found: manifest unknown: manifest unknown.
See 'docker run --help'.

These messages clearly point to the inability of the Docker client to retrieve the necessary metadata for the specified image version from the remote registry.

2. Root Cause: Technical explanation of the underlying cause.

The docker-manifest-not-found error occurs when the Docker client, after resolving the registry hostname, attempts to fetch the image manifest for a given repository and tag but receives a “not found” response from the registry. The manifest is a critical piece of metadata that tells Docker how to assemble the image from its various layers.

Several underlying reasons can lead to this specific error:

Incorrect Image Name or Tag: This is the most frequent cause. There might be a typo in the repository name (e.g., myrepo/myimage vs. myrepo/my-image), the image name itself, or the specified tag (e.g., v1.0 vs. 1.0).
Tag Does Not Exist: The specified tag (e.g., latest, dev, 1.2.3) simply does not exist for that particular image repository in the target registry. This can happen if the image was never pushed with that tag, or if the tag was subsequently deleted.
Image Deleted or Moved: The entire image repository or a specific tagged version of it might have been removed from the registry by its maintainers.
Private Repository Access Issues: If the image resides in a private registry (e.g., Docker Hub private repositories, AWS ECR, Google Container Registry, Azure Container Registry), the user might not be authenticated (docker login not performed or expired credentials) or might lack the necessary permissions to access the image.
Registry Issues: Less common, but the Docker registry itself might be experiencing temporary outages, misconfigurations, or replication delays, leading to manifests being temporarily unavailable.
Platform Mismatch (less common for this specific error, but possible): While manifest unknown usually points to the tag itself, in some edge cases, if a registry only serves platform-specific manifests and the requested platform isn’t available for the given tag, it could contribute. However, typically, this would result in a different error or a successful pull of a non-runnable image.

3. Step-by-Step Fix: Accurate fix instructions. You MUST use “Before:” and “After:” labels for code comparison blocks.

Resolving the docker-manifest-not-found error involves systematically checking the common causes. Follow these steps to diagnose and fix the issue:

Verify Image Name and Tag for Typos: The first and simplest step is to meticulously check the image name and tag for any typographical errors. Even a single character mismatch can lead to this error.

Before:
```
docker pull myregistry/myimage:v1-0 # Typo: should be v1.0
```
After:
```
docker pull myregistry/myimage:v1.0 # Corrected tag
```
Confirm the Tag Exists in the Registry: Browse the Docker registry (e.g., Docker Hub website, AWS ECR console, Google Cloud Console) to verify that the specific tag you are trying to pull actually exists for the image. For public images on Docker Hub, you can often use docker search or visit the image’s page.

Before:
```
# Attempting to pull a non-existent tag
docker pull myregistry/myimage:nonexistent-tag
```
After:
```
# After checking the registry, you find the correct tag is '2.0'
docker pull myregistry/myimage:2.0
```
Specify an Explicit and Valid Tag: Avoid relying solely on the latest tag, as it can be ambiguous, outdated, or even non-existent if the image maintainer hasn’t explicitly tagged an image as latest. Always prefer using specific version tags.

Before:
```
# Relying on 'latest' which might not exist or be the intended version
docker pull myregistry/myimage:latest
```
After:
```
# Using a specific, verified tag
docker pull myregistry/myimage:1.5.3
```

Authenticate to Private Registries: If the image is hosted in a private registry, you must be logged in with appropriate credentials. Ensure your docker login command was successful and your session hasn’t expired.

Before:

# Attempting to pull from a private registry without logging in
docker pull private.registry.com/my-private-image:1.0

After:

# First, log in to the private registry
docker login private.registry.com

# Then, pull the image
docker pull private.registry.com/my-private-image:1.0

Check Registry Status: In rare cases, the issue might be with the Docker registry itself. Check the status page for Docker Hub (status.docker.com) or your cloud provider’s status page for their respective container registries.

4. Verification: How to confirm the fix works.

After applying the potential fixes, you can verify that the issue is resolved by successfully pulling and optionally running the Docker image.

Successful Image Pull: Execute the docker pull command with the corrected image name and tag. A successful pull will show progress bars for downloading layers and conclude without error.

$ docker pull myregistry/myimage:v1.0
v1.0: Pulling from myregistry/myimage
Digest: sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Status: Downloaded newer image for myregistry/myimage:v1.0
docker.io/myregistry/myimage:v1.0

List Local Images: Confirm the image is now present in your local Docker image cache using docker images.

$ docker images
REPOSITORY             TAG       IMAGE ID       CREATED        SIZE
myregistry/myimage     v1.0      abcdef123456   2 days ago     123MB

Run a Container (Optional but Recommended): To fully verify, try running a simple container from the newly pulled image. This confirms that the image is not only pulled but also functional.
```
$ docker run --rm myregistry/myimage:v1.0 echo "Image pulled and running successfully!"
Image pulled and running successfully!
```

If all these steps complete without errors, the docker-manifest-not-found issue has been successfully resolved.

5. Common Pitfalls: Key mistakes to avoid.

When dealing with docker-manifest-not-found, several common mistakes can prolong troubleshooting:

Assuming latest is always current or exists: The latest tag is merely a pointer and can be updated, deleted, or never even assigned by image maintainers. Always verify the existence of latest or, better yet, use explicit version tags for stability and reproducibility.
Ignoring case sensitivity: While Docker Hub generally normalizes repository names to lowercase, some private registries or specific image names/tags might be case-sensitive. Double-check the exact casing.
Forgetting docker login for private images: This is a very common oversight. If an image is in a private repository, you must authenticate your Docker client to that registry before attempting to pull.
Misinterpreting network issues: Sometimes, a network connectivity problem (e.g., DNS resolution failure, firewall blocking access to the registry) can manifest with similar-looking errors. Ensure basic network connectivity to the registry host.
Confusing manifest not found with image not found: While related, manifest not found specifically indicates that the metadata for a specific tag is missing. image not found might imply the entire repository doesn’t exist. The fix focuses on the tag and its manifest.
Not checking the correct registry: Ensure you are attempting to pull from the correct registry. If an image is hosted on gcr.io, trying to pull it from docker.io (Docker Hub) will obviously fail.

Understanding errors that are similar to docker-manifest-not-found can help in broader troubleshooting of Docker image issues:

docker-image-not-found: This error typically occurs when the Docker daemon cannot find the specified image repository at all, rather than just a specific tag’s manifest. It suggests that the entire image name (e.g., myregistry/nonexistent-repo) is incorrect or the repository has been completely removed from the registry. The fix often involves verifying the full repository path.
docker-unauthorized: This error indicates that your Docker client lacks the necessary authentication or authorization to access the specified image or registry. It commonly appears when trying to pull from a private repository without having performed docker login or with expired/incorrect credentials. Unlike manifest not found, it’s a direct access denial.
docker-tag-not-found: While very similar to docker-manifest-not-found, some older Docker versions or specific registry implementations might return an error message explicitly stating “tag not found” instead of “manifest not found.” The underlying cause and resolution steps are largely identical, focusing on verifying the existence and correctness of the image tag.