A Verdaccio uplink is a remote registry it proxies. The uplink keys cache, maxage, timeout, fail_timeout and max_fails decide whether tarballs are stored, how long metadata stays fresh, and when Verdaccio stops asking a failing upstream. Defaults are true, 2m, 30s, 5m and 2.
The settings
From the Verdaccio uplinks documentation:
| Key | Default | Purpose |
|---|---|---|
cache | true | Cache remote tarballs in storage |
maxage | 2m | How long cached metadata stays valid |
timeout | 30s | Request timeout for the uplink |
fail_timeout | 5m | Window after which a request counts as a failure |
max_fails | 2 | Maximum failed requests allowed |
auth | disabled | Sets the Authorization header |
headers | disabled | Custom headers sent to the uplink |
Durations use NGINX style units such as 100ms, 10m or 30s.
What this means for freshness
maxage is about metadata, the list of versions and tags. With the default 2m, Verdaccio re-checks the upstream for new versions frequently. A longer value reduces upstream traffic and makes installs less dependent on the upstream being up. It also means a new release, or a corrected one, takes longer to show.
For security this cuts both ways. A malicious version published upstream appears in your mirror within minutes at the default. A longer maxage delays that a little, but it is no substitute for a deliberate delay or review policy, because the time scale is minutes, not days.
What this means for outages
With cache: true, tarballs fetched once are stored, so repeat installs of the same version do not need the upstream. That is the outage protection many teams want from a mirror. Install versions you need at least once through the mirror while the upstream is healthy, for example in a CI warm up job, so they are cached.
timeout, fail_timeout and max_fails govern how Verdaccio treats a flaky upstream. Short timeouts make installs fail fast when the upstream is slow, while long ones make builds hang. Tune them to what your pipeline can tolerate.
Tarballs on other hosts
The docs note that Verdaccio fetches a tarball only from a URL that a configured uplink serves. Registries that host tarballs on a separate CDN host are fetched through an autogenerated proxy that appears in logs as verdaccio-<package>. With log level http, each tarball fetch is logged with its target and uplink, and a refused off uplink fetch is logged as a warning, "refused off-uplink tarball fetch".
That warning is worth alerting on. It tells you that a package metadata file pointed somewhere your configuration did not expect.
Review checklist
- Which uplinks exist, and does each package pattern name the right one?
- Is
cacheon for uplinks you rely on during outages? - Is
maxagea deliberate choice rather than the default? - Are timeouts shorter than your CI job timeout?
- Are warning logs shipped and watched?
Safeguard's dependency scanning and SBOM generation help you see what your mirror delivered, with a free scan at gold.safeguard.sh/scan.
Quick check
Does maxage control how long tarballs are kept?
No. It controls how long cached package metadata is treated as valid. Tarball storage follows the cache setting.
Does a mirror protect me from a new malicious version?
Not by itself. With a short maxage, new upstream versions appear quickly. Add a review or delay policy.
Sources
Last reviewed: 19 October 2026.
