Images pulled via Docker Proxy Cache do not appear in Harbor Project UI

Products

• VMware Tanzu Platform - Kubernetes

Issue/Introduction

Users may observe a scenario where specific container images pulled through Harbor, which is configured as a proxy cache for an upstream registry, do not appear in the Harbor Project UI or repository list.

While the docker pull command completes successfully on the client machine and the image is available for use locally, the Harbor repository does not update to reflect the cached image. This issue may affect specific images regardless of size, while other images cache correctly.

Environment

• VMware vCenter Server 8.x

• vSphere with Tanzu (Supervisor Services)

• Harbor Container Registry 2.x

• Harbor configured as a Proxy Cache for an upstream registry (e.g., JFrog Artifactory, Docker Hub)

Cause

The Harbor proxy cache mechanism relies on a specific sequence of HTTP requests from the client to trigger the internal caching function:

1. A HEAD request to verify the image digest.

2. A GET request to fetch the manifest content.

If the Docker client (or other container runtime client) already retains a cached copy of the image manifest locally, it may send the HEAD request to verify existence but skip the GET request. If Harbor does not receive the specific GET request for the manifest, the proxy cache logic is not triggered. As a result, the image content is not saved to the Harbor proxy repository, and the UI is not updated, even though the client successfully validates the image.

Resolution

To resolve this issue and force Harbor to cache the missing image, a manual HTTP GET request must be sent to the Harbor manifest URL. This action simulates the missing client request and triggers the proxy cache function.

Execute the following curl command from a terminal that has network access to the Harbor registry:

curl -kv -u '<username>:<password>' https://<harbor_fqdn>/v2/<proxy_project_name>/<repository_name>/manifests/<tag_or_digest>

Note: Replace <username>, <password>, <harbor_fqdn>, <proxy_project_name>, <repository_name>, and <tag_or_digest> with the values relevant to the affected environment.

Once the command executes successfully, refresh the Harbor UI to verify that the image is now listed in the proxy cache project.

Additional Information

During troubleshooting, reviewing the harbor-core logs may reveal that the standard log entry stating fetch it from remote repo is absent for the affected image pull attempt. This absence confirms that Harbor did not attempt to reach the upstream registry because the necessary GET trigger was never received from the client.