Overview / Introduction
The same Docker pull may return different HTTP errors depending on the repository type. From a Local repository, a 403 may be returned with an Xray policy block. From a Virtual repository that aggregates the same Local repository, a 404 manifest unknown will be returned. Developers often treat the Virtual 404 as a missing image, which sends troubleshooting in the wrong direction.
Symptoms & error messages
-
Docker pull of a blocked image directly from a Local repository fails with DENIED, an Xray download blocking policy message, and HTTP 403.
-
Docker pull of the same image through a Virtual repository that aggregates that Local repository fails with HTTP 404 and manifest unknown.
-
The image exists in the Local repository and the tag is valid → the 404 is not caused by a missing manifest.
Local repository response:
docker pull <JFROG_URL>.jfrog.com/docker-LOCAL/myimage:tag1
error from registry: {"errors":[{"code":"DENIED","message":"Artifact download request rejected:
myimage/tag1/manifest.json was not downloaded due to the download blocking policy configured in
Xray for ..."Virtual repository response:
docker pull <JFROG_URL>.jfrog.com/docker-VIRTUAL/myimage:tag1
HTTP 404 not found: manifest unknown: The named manifest is not known to the registry.
Cause
This behavior is by design and aligned with current Artifactory logic.
Local repositories: When pulling directly from a Local repository, Artifactory explicitly evaluates download interceptors and Xray policies. If an artifact is blocked, it immediately returns an HTTP 403 Forbidden (blocked policy configured in Xray).
Virtual repositories: When pulling through a Virtual repository, Artifactory iterates through all aggregated member repositories. The search and resolution order is always Local repositories first → then remote repository caches → then the remote repositories themselves, with the order inside each category set by the member order in the Selected Repositories list.
-
If a member repository fails to serve a manifest due to an Xray block, the virtual logic treats that manifest as unavailable in that specific repository and moves to the next member.
-
If none of the other member/aggregated repositories hold the tag (returning 404), Artifactory aggregates the result and returns an HTTP 404 Manifest Unknown error to comply with the official Docker specification.
A useful consequence of the resolution order: if another member repository holds the same tag and is not blocked, the pull through the Virtual repository succeeds and serves that copy instead. The 404 only surfaces when the blocked member was the only member holding the tag.
The block itself can originate from either Xray policy action, Block Download on artifacts with violations at/above the configured severity, or Block Unscanned Artifacts, which blocks artifacts that have not yet been indexed and scanned.
Step-by-step remediation
There is no repository/global configuration to make a Virtual repository return 403 for this case; the aggregation logic and Docker specification compliance determine the response.
When developers encounter an HTTP 404 Manifest Unknown error for an image known to exist:
-
In the Artifactory UI, browse to the artifact in the repository tree and open the Xray tab. It displays the most recent scan status and a summary of any security violations, including violations that block downloading.
-
Perform a test pull of the same image directly against the targeted Local repository to trigger the explicit 403 response
Related resources