ARTIFACTORY: Why Artifacts Might Not Be Cached in an Artifactory Smart Remote Repository

Disclaimer on Edge Nodes
Please note that the information below does not apply to Artifactory Edge nodes. Artifacts are only cached on an Edge node after they are pulled through the Edge. Edge nodes do not support preemptive caching or pull replication.


Introduction
In Artifactory, a Smart Remote Repository extends the capabilities of a standard remote repository by allowing more advanced replication and caching features. Despite these advantages, administrators may occasionally encounter unexpected behavior—such as artifacts failing to populate the remote-cache repository. This article highlights the most common reasons why artifacts might not be cached and provides a step-by-step approach to resolving them. Whether you are new to Artifactory or an experienced DevOps engineer, the insights offered here will help you keep your repositories running smoothly, ensure efficient replication, and ultimately streamline your artifact management process.


Common Issues and Resolutions

Issue #1: Incorrect Repository URL Configuration

When configuring a Smart Remote Repository, some package types require the repository URL to be prefixed with the appropriate api/<package_type> path. If this prefix is missing or incorrect, artifacts will not be cached.
Example (On-Premises):

http://<JFrog_URL>/artifactory/api/<package_type>/<repository_key>

Example (Cloud):

https://<servername>.jfrog.io/artifactory/api/<package_type>/<repository_key>

The prefix is required for these package types:

For PyPI repositories, the registry URL also differs depending on whether the target is a local or remote repository on the remote Artifactory instance:

Local PyPI Example:
- URL: http://<JFrog_URL>/artifactory/pypi-local/
- Registry URL: http://<JFrog_URL>/artifactory/api/pypi/pypi-local/

Remote PyPI Example:
- URL: http://<JFrog_URL>/artifactory/pypi-remote/
- Registry URL: http://<JFrog_URL>/artifactory/api/pypi/pypi-remote/

For more details, see Configure a Smart Remote Repository.


Issue #2: Artifacts Not Downloaded, Therefore Not Cached

Even if the Smart Remote Repository is configured correctly, you may notice that the remote -cache repository remains empty. Artifacts in Artifactory are only cached once they have been requested (i.e., downloaded). If no download occurs, the -cache repository stays empty and you may see a message like, “This item is not cached.”

 

Resolving Empty Cache for a Smart Remote Repository
Enabling active replication on a Smart Remote Repository allows Artifactory to proactively populate a remote cache through pull replication, instead of waiting for artifacts to be fetched on demand. This approach is particularly useful if network latency makes on-demand retrieval too slow for your needs.

Artifactory supports two methods for pull replication:
-Scheduled Pull
The remote repository invokes pull replication on a defined schedule, running asynchronously at regular intervals to synchronize local, remote, or virtual repositories.

-Event-Based Pull (Requires Enterprise License)
Pull replication occurs in near real-time. Any artifact creation, copy, move, or deletion immediately triggers replication to the target, making new or updated files available without waiting for the next scheduled run.
This flexibility ensures that even in high-latency or mission-critical environments, artifacts are readily available in the remote cache as soon as they are introduced in the source repository. For more information, see our pull replication documentation.

 1. Enable Active Replication (Enterprise License Required)
- In the Replications tab of the Smart Remote Repository, check the option Enable Active Replication of This Repository.
- If Enable Event Replication is turned on, Artifactory will replicate artifacts immediately after specific events (upload, delete, property change), rather than waiting for the CRON-based schedule.

 2. Set a Cron Expression
Artifactory uses Quartz-style CRON expressions, which typically include 6 or 7 fields. For example, to run replication every Friday at 8:00 AM:

0 0 8 ? * FRI

- If you see an “Invalid cron expression” error while using a classic 5-field format (e.g., 0 8 * * 5), update it to the correct Quartz format (e.g., 0 0 8 ? * FRI).

Manually Trigger Replication for Existing Artifacts
If there are already artifacts in the remote repository that you need to cache, run the replication job manually or wait for the next scheduled replication. Replication must occur at least once to populate the -cache repository with existing artifacts.

 
 


Conclusion

 1. Repository URL Prefix: Always ensure you include api/<package_type> for package types that require it.
 2. Caching Requires Downloads: Artifacts will not appear in the -cache repository unless they’ve been requested or replicated.
 3. Replication Settings: Configure Enable Active Replication, set a valid CRON schedule, and consider Event Replication (if licensed) to ensure timely caching.
 4. Existing Artifacts: If artifacts are already in the repository, run or wait for replication to cache them.

For additional resources and a step-by-step guide, refer to:
JFrog Documentation: Smart Remote Repositories
Cron Trigger Tutorial (Quartz)