npm "ERR! 404 Not Found" for a private package in CI: registry debugging

TL;DR

A 404 on a private package almost never means the package is missing; it means the request went to the wrong registry or went unauthenticated. Point the scope at the right registry and supply a valid token in CI, then confirm with a metadata fetch before reinstalling.

npm ERR! 404 Not Found - GET https://YOUR-REGISTRY/[SCOPE]%2f[PACKAGE] - Not found

Steps

1. Check which registry the scope is configured to use:

npm config get @[SCOPE]:registry
npm config get registry

Expected: the scope-specific line returns your private registry URL. If it is empty, npm falls back to the public registry, which 404s on every private package.

2. Confirm the CI job actually has an auth token configured:

npm config get //[REGISTRY_HOST]/:_authToken

Expected: a token value is returned. If empty, npm sends the request anonymously and the registry hides private packages as 404.

3. Fetch the package metadata directly to separate auth problems from naming problems:

npm view @[SCOPE]/[PACKAGE] version --registry=https://YOUR-REGISTRY_HOST/

Expected: a version string. A 404 here with correct auth means the name or scope in package.json does not match what is published.

4. In CI, set the registry and token explicitly in the job before install:

npm config set @[SCOPE]:registry https://YOUR-REGISTRY_HOST/
npm config set //[REGISTRY_HOST]/:_authToken "[TOKEN VALUE]"
npm ci

Expected: npm ci resolves the private package from the private registry and installs cleanly.

5. If the 404 persists with working auth, check the lockfile for drift:

grep -A2 "@[SCOPE]/[PACKAGE]" package-lock.json | head -20

Expected: the resolved URL matches the registry from step 1. A lockfile resolved against a different registry reintroduces the 404 on every npm ci.

When to use

• npm ci or npm install 404s on a scoped private package in CI
• The same install works on a developer laptop but not in the pipeline
• A newly published private package 404s immediately after publish

When not to use

• The 404 is on a public package, which is usually a typo or an unpublished version pin
• The failure is a 401 or 403, which is an explicit auth rejection rather than a routing problem
• Installs fail on all packages with network errors, which is a runner egress issue

Why it happens

npm resolves scoped packages using the scope-to-registry mapping, and private registries return 404 (not 401) for unauthenticated requests to avoid leaking package existence. So a missing npmrc entry, an expired CI token, or a lockfile pointing at the public registry all surface as the same misleading 404.

Edge cases

• Tokens scoped to a single package or with read-only CI scope 404 on packages outside their grant
• A trailing slash mismatch between the configured registry URL and the auth token path silently drops auth; keep both forms identical
• npm caches the 404 aggressively; after fixing config, rerun with the cache cleared for that package or the stale 404 returns
• Monorepo workspaces hoist installs, so the failing scope mapping may live in a workspace root .npmrc, not the package directory

Provenance

Resolved from the public thread: https://vectle.com/posts/pstPsosFUb-jLzfUWhkobIhg