Image not found
The registry could not locate the requested image repository or user namespace.
Usually happens because:
- ☑ Repository name spelling typo
- ☑ Missing namespace prefix path
- ☑ Private repository accessed without login
🔍 Quick Checklist:
What is Image not found?
This error occurs when you attempt to pull or run an image that does not exist on the remote registry, or when the namespace/repository spelling is incorrect. In Docker registries, images are structured as 'namespace/repository:tag'. If the namespace or repository is missing, the engine cannot resolve the request and reports that the image was not found.
Common Causes
- Mismatched image repository spelling: Typo in the name of the container repository.
- Incorrect namespace prefix: Omitting the user/organization namespace (e.g. pulling 'mysql' instead of 'library/mysql' when namespace targets are altered).
- Active registry resolution failure: Local DNS or network connection blocks the client from looking up registry repositories.
| Cause | Frequency |
|---|---|
| Spelling typo in repository name | ⭐⭐⭐⭐⭐ |
| Missing namespace prefix | ⭐⭐⭐⭐ |
| Registry DNS lookup block | ⭐⭐ |
Common Mistakes
- Forgetting that private repositories will return 'image not found' instead of 'access denied' to hide their existence from unauthorized users.
- Omitting the namespace segment for custom repositories (e.g. pulling `my-app` instead of `my-org/my-app`).
How to Fix
Docker Operations & Verification
Locate public image names using the search command.
$ docker search postgres
# Outputs list of matching public repositories, stars, and official ratingsPlatform Specific Fixes
Standard CLI lookup commands on Linux machines.
docker search node
docker pull node:20Best Practices
- Maintain documented image paths inside README setup scripts.
- Use pinned image digests (`image: tag@sha256:xxxx`) inside production files to guarantee resolutions.
Frequently Asked Questions (FAQ)
Q: Why does it say image not found?
The registry could not resolve the repository path name you requested. Check for typos or missing namespace tags.
Q: How do I find public images?
You can search directly using the CLI command 'docker search <image_name>' or browse Docker Hub.
Q: Can this happen due to private repository settings?
Yes. If a repository is private, the registry responds with a generic 'image not found' or 'pull access denied' to protect repository privacy.
Q: How do I specify a tag?
Append a colon and the tag version to the repository name, like 'ubuntu:22.04'. If omitted, Docker defaults to ':latest'.