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.

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