## 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

```text
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