Understanding upstream fallback and 404s in Chainguard Libraries

• Built-in upstream fallback is available for all three ecosystems (Java, Python, and JavaScript). It is off by default. Enable it as a policy with chainctl, for example: chainctl libraries entitlements create --ecosystems=JAVASCRIPT --policy=CHAINGUARD_AND_UPSTREAM (substitute JAVA or PYTHON). The policy can also be managed in the Chainguard Console.
• When fallback is on and a package is not yet built by Chainguard, it is sourced from the upstream public registry after a cooldown period, then cached. The default cooldown is 7 days (configurable); policy changes can take up to about 30 minutes to apply.
• The Chainguard repository is a screened, partial mirror, not a full mirror of the public registry. Packages are screened, and some may be delayed by the cooldown or blocked.
• Fallback has been validated with different repository managers per ecosystem (for Java, Artifactory and Nexus are tested; Cloudsmith and Google Artifact Registry are noted as not yet tested). Check your ecosystem's global-configuration page for current coverage.

Registry URL vs. the upstream path (avoiding 404s)

For a direct client (npm, pnpm), point the registry URL at the ecosystem path (for example /javascript/), not at the -upstream path. However, your credential must be keyed to the whole libraries.cgr.dev host so it covers both the /javascript/ and /javascript-upstream/ paths; a missing credential on the upstream path produces 404s for fallback packages.

In a repository manager, the -upstream path is a real endpoint that is sometimes configured deliberately. For example, the Google Artifact Registry setup for JavaScript adds a second remote (javascript-chainguard-upstream) pointing at https://libraries.cgr.dev/javascript-upstream, and it too needs its own credential entry or you will get 404s for upstream-fallback packages.

When a checksum differs from the public registry

Chainguard rebuilds packages from source, so a checksum can differ from the public registry. If a lockfile pins the public checksum, update the hashes in place with chainctl libraries update-hashes (flags include --registry-url for repository-manager mode, --replace, and --parent). Run it once per lockfile outside node_modules/.