Introduction
This article explains how Artifactory behaves and how the resolution logic varies for remote repositories depending on the upstream status. We cover several scenarios based on upstream availability and explain how Artifactory handles each situation. We analyze the resolution logic across three common scenarios: healthy connectivity, delayed responses, and immediate service failures.
Artifact Resolution Order:
When a client requests an artifact through a Virtual Repository, Artifactory applies a resolution sequence to optimize speed and minimize external network calls:
Local Repositories: Direct check for locally hosted binaries.
Remote Repository Caches: Check for previously cached remote artifacts from remote cache repository.
Remote Upstream: Fetch and serve the artifact from the external source if it is not found in the first two steps.
Scenario 1: Upstream Reachable and Responding Normally
In a healthy environment, Artifactory functions as a proxy. When an artifact is not found in the local or remote cache repositories, Artifactory forwards the request to the remote endpoint and retrieves the artifact from the upstream source.
Below is an example of the expected Artifactory log when the remote repository is functioning as expected.
Artifactory request log:
2025-12-09T14:00:54.895Z|af59fb9c215ee09e584cf299d3639b65|XX.XXX.XX|admin|GET|/api/npm/test-virtual/nginx|200|-1|11023|1623|npm/11.6.2 node/v25.2.1 darwin arm64 workspaces/false
Artifactory request out log:
2025-12-09T14:00:54.318Z|af59fb9c215ee09e584cf299d3639b65|test-remote||HEAD|https://registry.npmjs.org/nginx|200|0|0|393
2025-12-09T14:00:54.411Z|af59fb9c215ee09e584cf299d3639b65|test-remote||GET|https://registry.npmjs.org/nginx|200|0|0|36
Scenario 2: Remote repository response is delayed or unavailable
Artifactory is designed to ensure build continuity even when upstreams are unstable. If an artifact is already present in the Remote Repository Cache, Artifactory will serve that cached version even if the remote registry is unreachable or manually set to "Offline."
For this test scenario, the remote repository was manually set to offline in Artifactory, and the package was then requested through the virtual repository. Since the artifact was already cached, Artifactory was still able to serve it successfully.
Log Analysis (Cached Content)
The logs below show a 304 (Not Modified) or 200 response from the cache while the remote was unavailable. No request-out entries appear because Artifactory does not attempt to contact the offline upstream.
2025-12-09T14:13:49.018Z|03e9e4cc3ee646d3c1155759b01b239f|XX.XXX.XX1|admin|GET|/api/npm/test-virtual/nginx|304|-1|65|12|npm/11.6.2 node/v25.2.1 darwin arm64 workspaces/false
2025-12-09T14:13:49.328Z|d78b8da8271079314b78b6994708e22f|XX.XXX.XX|admin|GET|/api/npm/test-virtual/commander|304|-1|65|18|npm/11.6.2 node/v25.2.1 darwin arm64 workspaces/false
2025-12-09T14:13:49.588Z|4e6fcd49f5d8799ee14d2c32b6aa5540|XX.XXX.XX|admin|GET|/api/npm/test-virtual/prompt|304|-1|65|18|npm/11.6.2 node/v25.2.1 darwin arm64 workspaces/false
2025-12-09T14:13:49.589Z|ebd8d02c71ec1a77a5330e1f998d55c1|XX.XXX.XX|admin|GET|/api/npm/test-virtual/chalk|304|-1|65|21|npm/11.6.2 node/v25.2.1 darwin arm64 workspaces/false
Important settings to note:
Socket Timeout:
Defines the duration (in milliseconds) that Artifactory will wait to establish a connection and receive data from a remote upstream. If this timeout is reached, Artifactory marks the remote repository as “assumed offline” for the duration specified by the Assumed Offline Period.
Assumed Offline Period:
When a connection error occurs, this parameter specifies how long (in seconds) Artifactory should wait before performing an online check to determine whether the repository can be reinstated as active. A value of 0 disables the offline assumption entirely; Artifactory will always attempt to connect to the remote repository whenever a request requires it.
Scenario 3: Remote Repository Returns a 503 Response
Latest versions of Artifactory (post-v7.49.x) include a fix for a previously reported issue where repositories would not go offline quickly enough after repeated failures.
When an upstream returns a persistent 5xx error or is entirely unreachable, Artifactory transitions the repository to an Offline status. This prevents the system from being bogged down by "Read Timeouts" on every subsequent request.
Expected Behavior:
- The first request attempts to reach the upstream.
- The upstream fails (e.g., Connection Refused).
- Artifactory logs the failure and sets the repo to Offline.
- Subsequent requests immediately receive a 404 Not Found (if not cached), sparing the client from waiting for a full socket timeout.
Validation scenario:
For validation, we configured a remote repository pointing to an unreachable endpoint (http://maven.twttr.com/) and attempted to fetch an artifact through the virtual repository. As expected, Artifactory immediately returned a 404, and shortly afterward, the remote repository was automatically transitioned to offline status.
Example log entry:
2025-12-5T02:06:18.611Z [jfrt ] [INFO ] [78cfa1c8bdf3926287730e233070592e] [m.OnlineMonitorServiceImpl:191] [online-monitor-1] - maven-replication is inaccessible.
Setting as offline!
The client receives the 404 response immediately, confirming the intended behavior.
Summary
Case 1: Upstream reachable → artifacts fetched from upstream if not cached.
Case 2: Upstream delayed/unavailable → cached artifacts served; offline handling based on Socket Timeout and Assumed Offline Period.
Case 3: Upstream returns 503 → repository marked offline; 404 returned to client.
These scenarios illustrate how Artifactory manages remote repositories and resolution logic depending on upstream status.