Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

npm install fails with E401 against a private Nexus registry

Errornpm error code E401

Short answer

E401 means the registry asked for credentials and npm sent none that it accepts. In practice the .npmrc has no login for that exact registry URL, the token is scoped to another host, or an environment variable in .npmrc is empty. Log in against the registry, then compare the URL in .npmrc.

  • Applies to npm 10, npm 11, Node.js 22, Sonatype Nexus Repository
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    List the registry and auth lines npm really reads, then ask the registry who you are.

    npm config ls
    npm whoami --registry=https://nexus.example.com/repository/npm-group/
  2. 2Match what you see, then jump to its fix

    1. 1npm whoami against the private URL also answers 401No login is stored for that registryFix
    2. 2A token exists in .npmrc, yet the 401 is still returnedThe token is scoped to a different registry addressFix
    3. 3Works on your laptop; fails in CI or Docker, where the token variable is missingThe variable used in .npmrc is not setFix
    4. 4npm install works inside the project, but npm install -g of a private package returns 401The project .npmrc is not read for a global installFix

What does the error look like?

  • npm error code E401
  • npm error Unable to authenticate, need: BASIC realm="Sonatype Nexus Repository Manager"
  • npm ERR! code E401

Cause 1 of 4

No login is stored for that registry

1Check

npm saves credentials in a .npmrc file, keyed by registry. A fresh machine, a new CI runner or an expired token has none for this host.

npm config ls

2Fix

Log in against the private registry URL. Add a scope if only your company packages come from it.

npm login --registry=https://nexus.example.com/repository/npm-group/
# only for packages under one scope
npm login --scope=@mycorp --registry=https://nexus.example.com/repository/npm-group/

3Verify

whoami prints your user name, then the install runs.

npm whoami --registry=https://nexus.example.com/repository/npm-group/
npm install

Confirmed by docs.npmjs.com

Did this fix it?

Cause 2 of 4

The token is scoped to a different registry address

1Check

npm only sends _auth, _authToken or username and password to the registry whose address prefixes the key. An unscoped _authToken line is not valid, and a prefix that differs by host or path never matches the URL in your registry setting.

grep -n "registry\|_auth" .npmrc ~/.npmrc

2Fix

Make the credential line start with the same host and path as the registry line.

@mycorp:registry=https://nexus.example.com/repository/npm-group/
//nexus.example.com/repository/npm-group/:_authToken=${NPM_TOKEN}

3Verify

npm whoami now succeeds for that registry.

npm whoami --registry=https://nexus.example.com/repository/npm-group/

Confirmed by docs.npmjs.com

Did this fix it?

Cause 3 of 4

The variable used in .npmrc is not set

1Check

npm replaces ${NAME} with the variable's value. If the variable is undefined, the text stays as it is, so the registry receives a token that reads ${NPM_TOKEN}.

echo "${NPM_TOKEN:+set}"
grep -n "_authToken" .npmrc

2Fix

Export the variable in the job or build step that runs the install. Adding a question mark after the name, as in ${NPM_TOKEN?}, makes an undefined value empty and not literal.

export NPM_TOKEN=<token-from-your-registry-admin>
npm install

3Verify

The install in that environment reaches the registry without E401.

npm whoami --registry=https://nexus.example.com/repository/npm-group/

Confirmed by docs.npmjs.com

Did this fix it?

Cause 4 of 4

The project .npmrc is not read for a global install

1Check

The per-project file is not read in global mode, so credentials stored only there are not seen by npm install -g.

npm config ls -l

2Fix

Put the registry and auth lines in the per-user file at ~/.npmrc for global installs.

npm login --registry=https://nexus.example.com/repository/npm-group/

3Verify

Repeat the global install.

npm install -g @mycorp/my-cli

Confirmed by docs.npmjs.com

Did this fix it?

How do I stop it coming back?

  • Keep the token in a CI secret and reference it as ${NPM_TOKEN} in .npmrc, never as plain text in git.
  • Scope private packages with @scope:registry so public packages still come from the public registry.
  • Run npm whoami with the registry flag as the first step of a CI install job.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.