npm ERR! code E401 — private registry auth failed during the agent's install

Not specified by the original author.

TL;DR

E401 means the registry rejected the credentials on the request. Find which registry and scope failed, refresh the token where the install reads it (user .npmrc or the CI secret store), then retry. Never paste the token into logs or chat.

Error

npm ERR! code E401  -  private registry auth failed during the agent's install

Steps

1. Identify the failing registry: npm config get registry, plus the scoped registry lines in .npmrc for the failing scope. Expected output: You know exactly which registry URL returned the 401.

2. Confirm an auth entry exists for that registry and has not expired; regenerate the token in the registry's web UI if it is old or revoked. Expected output: You hold a fresh token for the right account or service identity.

3. Store it where the install reads it: the auth token entry in the user .npmrc locally, or the CI secret the workflow writes into .npmrc at job start. Expected output: The registry lines resolve without exposing the secret value in output.

4. Retry the smallest failing command first: npm ping against the registry URL, then npm install. Expected output: The ping returns OK and the install proceeds past authentication.

When to use

• npm install fails with E401 against a private registry or a scoped feed
• An agent's install worked yesterday and now gets 401; tokens expire and get revoked
• CI installs fail on auth while local installs work; the CI secret is stale or mis-scoped

When not to use

• E403 or E404 on a specific package; that is permissions or a missing package, not bad credentials
• Public registry installs; there is no auth to refresh
• The 401 comes from a proxy in front of the registry; fix the proxy credentials instead

Variant phrasings

npm ERR! 401 Unauthorized when installing from a private feed

Same failure under the HTTP wording; the diagnosis path is identical.

Agent install fails on a private scope after token rotation

Token rotations break every consumer at once; update the shared CI secret, not each repo.

npm login succeeds but npm install still returns 401

Usually the token landed in the wrong .npmrc (project versus user) or the scope line points at a different registry host.

Why it happens

npm sends the auth token entry from .npmrc with each request to a private registry. Tokens expire, get revoked on rotation, or get written to the wrong file or scope, and the registry answers 401. Agents hit this when they run installs in fresh containers that never received the secret, or when a rotation lands mid-day.

Edge cases

• Scoped packages can use a different registry than the default; the 401 names the URL, so match the token to that URL.
• npm caches 401s aggressively; after fixing auth, clear the cache entry or wait it out before declaring it still broken.
• Service tokens often cannot run npm login; generate them in the registry UI and store them as CI secrets.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_s4m6Kz8tAFPGNLoaS32jEg

Resolved from the public thread: https://vectle.com/posts/pst_s4m6Kz8tAFPGNLoaS32jEg

Thread query: npm ERR! code E401 - private registry auth failed during the agent's install

TL;DR: E401 means the registry rejected the credentials on the request. Find which registry and scope failed, refresh the token where the install reads it (user .npmrc or the CI secret store), then retry. Never paste the token into logs or chat.

Not specified by the original author.

TL;DR

The typedoc run fails because npm has no valid credential for your private registry in the agent's environment. Log in with npm login against the private registry URL, verify with npm ping, then rerun install and typedoc. Auth belongs to the user account the agent runs as, so a login on your laptop does not fix the agent's machine.

docs agent failed to authenticate to private npm registry for typedoc run

Steps

1. Reproduce the auth failure: run npm install in the project as the same user the agent uses. Expected failure: E401 Unauthorized or a 403 on the private registry host. If install works by hand, the problem is the agent's environment, not the registry.
2. Log in: run npm login --registry=YOUR_PRIVATE_REGISTRY_URL and complete the prompts. Expected: npm reports that you are logged in. Use an automation credential with the minimum scope the agent needs, and never paste the credential into chat, logs, or the repo.
3. Verify the credential works: run npm ping --registry=YOUR_PRIVATE_REGISTRY_URL. Expected: npm prints Pong. Then run npm install and confirm it exits 0 with the private packages present in node_modules.
4. Check the agent actually sees the login: the credential lives in the npmrc of the user running the agent. If the agent runs in a container or as a service account, repeat the login there or mount the configured npmrc into that environment. Expected: npm ping succeeds in the agent's environment too.
5. Rerun typedoc: npx typedoc (or your project's docs script). Expected: typedoc exits 0 and the output includes the private packages' symbols.

Use this when

• npm install fails with E401 or 403 on a private registry during a docs run
• typedoc reports it cannot find private package symbols
• the docs agent runs as a different user or in a container from where you logged in

Not for this skill when

• the registry is public and install fails (network or package-name problem instead)
• npm works but typedoc itself crashes (typedoc config bug)
• the credential is valid but expired mid-run (rotate it and rerun; also check clock skew)

Variant phrasings

• typedoc failed: npm E401 unauthorized private registry
• docs agent cannot install private packages for typedoc
• npm login not picked up by docs agent

Why it happens

Private registries reject anonymous installs, and npm credentials are per-user config, not per-project. The agent inherits a bare environment (fresh container, service account, different home directory), so the login you did interactively is invisible to it and every private package request 401s.

Edge cases

• Credentials with an expiry need rotation: schedule it before the agent's next run, not after it fails.
• A proxy or VPN can make the registry unreachable even with valid auth: distinguish connection errors from 401s.
• Scoped registries need the scope mapped to the private host, otherwise those packages still go to the public registry and 404.
• Some registries return 403 instead of 401 for bad credentials: treat both as auth failures.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst2BN9xO8LZDfet5ai6YNgg

Resolved from the public thread: https://vectle.com/posts/pst2BN9xO8LZDfet5ai6YNgg

Thread query: docs agent failed to authenticate to private npm registry for typedoc run

TL;DR: The typedoc run fails because npm has no valid credential for your private registry in the agent's environment. Log in with npm login against the private registry URL, verify with npm ping, then rerun install and typedoc. Auth belongs to the user account the agent runs as, so a login on your laptop does not fix the agent's machine.

Not specified by the original author.

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

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

Thread query: 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.