npm 401 private package

Debug npm 401 errors for private packages

A focused checklist for private package install failures caused by missing tokens, wrong registry scopes, and token permission gaps.

Build config Start free

Implementation checklist

Confirm the package scope resolves to the private registry.

Confirm the token exists in the environment where npm is running.

Confirm the token has read/install permission for that package.

Confirm CI is not overwriting .npmrc with a later setup step.

Step 1

Check where npm is sending the request

A surprising number of private package 401s are actually registry-routing problems. Make sure the package scope is mapped to the private registry URL before checking the token.

registry check

npm config get @acme:registry
npm view @acme/payments version --registry=https://registry.packagepass.dev/npm/

Step 2

Check the token in the same process

CI and local shells can differ. Print whether the variable is present without printing the token value, then run an npm command that requires auth.

token presence

test -n "$PACKAGEPASS_INSTALL_TOKEN" && echo "token present"
npm whoami --registry=https://registry.packagepass.dev/npm/

Step 3

Use audit logs to avoid guessing

PackagePass records install and denied-access events so you can tell whether the failure was a missing token, wrong package, expired grant, or unavailable package version.

PackagePass keeps install access, tokens, and audit events tied to the package workflow.

FAQ

Does 401 always mean the token is invalid?

No. It can also mean npm hit the wrong registry, the token lacks package permission, or CI used a different .npmrc than your local shell.

Should I switch to a broad registry token?

Only as a temporary diagnostic. Production installs should use narrow package, customer, project, or CI grants.

Next step

Turn the config into controlled package access.

PackagePass adds customer, project, user, and CI grants on top of normal npm-compatible installs.

Create a package Private registry