Introduction
This article explains the list.manifest.json file and why it might show a "resource has expired" error, specifically when the cached metadata file is outdated or if the Metadata Retrieval Cache Period (MRCP) is set to 0 in the Artifactory Docker Remote repository. The list.manifest.json file is pulled from DockerHub using Docker backend APIs. However, this file is not stored in a fixed endpoint on DockerHub, leading to specific issues when attempting to download it via the UI.
Background
Modern applications must operate across various hardware architectures, like Intel and AMD processors, as well as ARM-based systems. Docker multi-platform manifests (also known as the “manifest of manifests”) address this need by enabling a single image tag to support multiple architectures.
The list.manifest.json is a multi-platform manifest that references multiple platform-specific images. When you pull an image, Docker automatically selects the appropriate image for your architecture.
In Artifactory, the list.manifest.json file is generated using metadata retrieved from several Docker /v2/ APIs. Unlike the structured storage and organization within Artifactory, DockerHub does not store the list.manifest.json file at a fixed endpoint. Therefore, there is no dedicated location on DockerHub to directly fetch the list.manifest.json file.
How Metadata Retrieval Works in Docker
When a user attempts to download the list.manifest.json file via the Artifactory UI, no activity is generated in the artifactory-request-out.log APIs. This is because the UI download operates independently of the Docker package type APIs, which are responsible for generating the list.manifest.json file. Each package type (such as Maven, NuGet, Docker, NPM, etc) has its own unique logic and required APIs for creating these metadata files.
Contrasting with Maven
For instance, in the case of Maven remote repositories with MRCP set to 0:
- Downloading the maven-metadata.xml file via the UI works because this file is stored in a fixed directory structure similar to how Artifactory retains it.
- This is not the case for Docker, which requires specific APIs to create its metadata files, such as list.manifest.json.
Example
To illustrate the behavior, consider the following scenario:
- A UI download of the list.manifest.json file generates zero entries in the artifactory-request-out.log.
- Performing a Docker pull for an 'alpine' image that is already present in a Docker remote repository (docker-gavri-0) with MRCP set to 0 generates the following log entries:
2026-01-26T10:03:20.004Z|3348e7c8509baf4a8940e9ab6032b556|docker-gavri-0||HEAD|https://registry-1.docker.io/v2/library/alpine/manifests/latest|200|0|9218|422
2026-01-26T10:03:20.248Z|3348e7c8509baf4a8940e9ab6032b556|docker-gavri-0||HEAD|https://registry-1.docker.io/v2/library/alpine/manifests/latest|200|0|9218|225
Conclusion
When MRCP is set to 0, Artifactory makes requests to the upstream repository for every metadata request, including constructing list.manifest.json. Attempting to fetch this file directly via the UI will not work because the required Docker APIs are not called. Hence, the "resource has expired" error is seen.
Recommendations
To avoid this error, it is recommended to:
- Use the appropriate Docker client commands to interact with Docker metadata.
- Adjust the MRCP setting to a low value (Above zero) to reduce the frequency of upstream checks.
If your remote repository upstream is Docker Hub, setting MRCP to 0 ensures you receive up-to-date metadata with every request. However, the vast majority of images on Docker Hub are not updated every hour. Therefore, we recommend increasing the MRCP to balance accurate metadata fetching with performance (example: set it to 3600 seconds/1 hour).
By understanding these behaviors and configuring your Artifactory and Docker settings accordingly, you can effectively manage the retrieval of list.manifest.json files and avoid the "resource has expired" error.