Introduction
When pulling a Docker image through Artifactory, the Docker client may return an error indicating that the image, tag, or manifest could not be found. In many cases, the image may still exist in the upstream registry or another Artifactory instance. Still, the request may fail due to repository path mismatch, incorrect remote configuration, authentication issues, cache behavior, or an incorrect Docker pull format.
This article provides a structured checklist to isolate where the failure is occurring.
Symptoms (Common error messages)
You may see one of the following errors while pulling a Docker image through Artifactory:
-
Error response from daemon: manifest for <IMAGE> not found: manifest unknown: The named manifest is not known to the registry.
-
Error response from daemon: pull access denied, repository does not exist or may require authorization.
-
Error response from daemon: unknown: Not Found
-
Error response from daemon: unauthorized: authentication required
-
Error response from daemon: denied: requested access to the resource is denied
Resolution
Step 1: Validate the Docker pull format
Confirm the pull command includes the Artifactory repository key, not just the upstream image path. A path that works against Docker Hub directly will fail through Artifactory if the repository key is missing.
docker pull <ARTIFACTORY_HOST>/<REPOSITORY_KEY>/<IMAGE_NAME>:<TAG>
Step 2: Confirm whether the image exists upstream
Pull the same image and tag directly from the upstream registry to rule out source-side issues. If the upstream pull also fails, the problem is the image name, tag, or upstream availability, not Artifactory.
docker pull <UPSTREAM_REGISTRY>/<IMAGE_NAME>:<TAG>
Step 3: Test the remote repository connection
Validate that Artifactory can reach the upstream URL via the repository's Test button. A successful test confirms connectivity only, it does not guarantee every tag or manifest can be resolved.
Step 4: Validate Smart Remote repository URL format
For a Smart Remote pointing to another Artifactory, the URL in the Smart Remote Repository configuration must include the Docker API path and source repo key. Pointing to the browser path instead of the API endpoint can make the test misleading, while manifest resolution still fails.
Correct:
https://<SOURCE_ARTIFACTORY_HOST>/artifactory/api/docker/<SOURCE_REPOSITORY_KEY>
Incorrect:
https://<SOURCE_ARTIFACTORY_HOST>/artifactory/<SOURCE_REPOSITORY_KEY>
Step 5: Check whether the artifact is cached or only available upstream
The remote-cache repository is populated only after an image is successfully pulled at least once.
Step 6: Check authentication and permissions
Confirm the user has Read access to the remote repository. In addition, if the requested image is not yet cached in the remote-cache repository, the user must also have Deploy/Cache permission on that repository, since Artifactory needs to write the freshly fetched image into the remote-cache during a first-time (uncached) pull.
If the upstream registry requires authentication, the corresponding credentials must be provided in the remote repository's Username and Password / Access Token fields as shown below.
Step 7: Review Artifactory request logs
Inspect the Docker API calls in the artifactory-request.log and use the response code to find the direction. If the request is forwarded upstream, review artifactory-request-out.log to confirm the upstream response. Both logs are located under $JFROG_HOME/artifactory/var/log/.
Look for the following Docker API calls:
/v2/<image>/manifests/<tag>
/v2/<image>/blobs/<digest>
Response
|
Possible direction
|
401
|
Authentication issue
|
403
|
Permission issue or upstream access restriction
|
404
|
Image/tag not found, path mismatch, or incorrect repository routing
|
5xx
|
Artifactory, network, proxy, or upstream availability issue
|
Step 8: Clear stale client-side assumptions
Re-authenticate and retry to rule out a stale local Docker client state. If the issue is intermittent or client-specific, reproduce it from another machine or CI runner with the same credentials.
If the issue persists, please collect the Docker pull command and support bundle for the On-Prem instance while opening a support case.