Maaz Zindani

Loading the index…

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

npm complains that _auth, _authToken, username or _password must be scoped to a registry

Errornpm WARN config `_auth`, `_authToken`, `username` and `_password` must be scoped to a registry.

Short answer

npm no longer accepts login settings that are not tied to one registry, so it never sends a token to the wrong host. Find the .npmrc file with a bare _authToken, _auth, username or _password line and put the registry address in front of it, for example //registry.npmjs.org/:_authToken. npm config fix can do it for you.

  • Applies to Node.js 24, npm 11
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    List the auth-looking lines in the project .npmrc, the user .npmrc and the global npmrc. Any hit that does not start with // is the line npm is complaining about. The first part of the error text names the file kind: user, project or global.

    grep -n -i -E "^(_auth|-auth|username|_password|email|certfile|keyfile)" .npmrc ~/.npmrc "$(npm config get prefix)/etc/npmrc"
  2. 2Match what you see, then jump to its fix

    1. 1`_authToken` must be renamed to `//registry.npmjs.org/:_authToken` in user configA bare _authToken, _auth, username or _password lineFix
    2. 2`_authtoken` is not allowed in user configA key npm cannot move to a registry, so it asks you to remove itFix
    3. 3The warning is gone but npm install answers 401 or 404 for a private package, or npm config fix attached the token to the registry you did not meanThe token is scoped, but to the wrong registry addressFix

What does the error look like?

  • npm WARN config `_auth`, `_authToken`, `username` and `_password` must be scoped to a registry.
  • Invalid auth configuration found: `_authToken` must be renamed to `//registry.npmjs.org/:_authToken` in user config
  • Please run `npm config fix` to repair your configuration.
  • ERR_INVALID_AUTH

Cause 1 of 3

A bare _authToken, _auth, username or _password line

1Check

Look at the lines the grep found. A line that starts with the key itself, such as _authToken=..., is what the npm docs call a bad config. The docs require these settings to be scoped to a specific registry, so that npm never sends credentials to the wrong host.

grep -n -i -E "^(_auth|username|_password)" .npmrc ~/.npmrc

2Fix

Put the registry address, without https:, in front of the key and end it with a colon. Keep the secret itself out of the file by reading it from an environment variable, which npm replaces when it reads the file. Or let npm attach the settings to the configured registry: npm config fix does exactly that.

# before: rejected
_authToken=${NPM_TOKEN}

# after: scoped to the npm registry
//registry.npmjs.org/:_authToken=${NPM_TOKEN}

# or let npm repair the file itself
npm config fix

3Verify

Run a command that needs the token. The warning is gone, and npm whoami prints the account name if the token is valid.

npm whoami

Confirmed by docs.npmjs.com

Did this fix it?

Cause 2 of 3

A key npm cannot move to a registry, so it asks you to remove it

1Check

npm's config code deletes a few forms instead of renaming them: a key spelled _authtoken or -authtoken, a username line without a _password line (or the other way round), and a certfile or keyfile that has no partner. The message then says the key is not allowed in that config file.

grep -n -E "^(_authtoken|-authtoken|username|_password|certfile|keyfile)" .npmrc ~/.npmrc

2Fix

Open the file in an editor and delete the offending lines, then write the setting again in its correct, scoped form. For a registry token the simplest way is to log in again, which stores a scoped token in your user .npmrc.

# 1. edit ~/.npmrc (or the project .npmrc) and delete the lines the grep listed
# 2. then log in again
npm login

3Verify

npm config fix reports nothing left to repair, and npm whoami answers.

npm config fix
npm whoami

Confirmed by github.com

Did this fix it?

Cause 3 of 3

The token is scoped, but to the wrong registry address

1Check

npm config fix attaches auth settings to the registry that is configured at that moment, which is registry.npmjs.org unless you changed it. A token for a private registry then ends up under the wrong address. The scope in the file must match the registry the package comes from.

npm config get registry
grep -n -E "registry|:_auth" .npmrc ~/.npmrc

2Fix

Map the package scope to its registry, and give the token under that registry's own address. A line with the host only applies to every scope that uses that host; a line with a path applies to that path only.

@myorg:registry=https://registry.example.com/myorg/
//registry.example.com/myorg/:_authToken=${PRIVATE_NPM_TOKEN}

3Verify

Ask that registry who you are, then install the private package.

npm whoami --registry=https://registry.example.com/myorg/
npm install @myorg/some-package

Confirmed by docs.npmjs.com

Did this fix it?

How do I stop it coming back?

  • Never write _authToken=... on its own line in any .npmrc; always start the line with the // registry address.
  • Keep tokens out of the repository: commit an .npmrc that reads ${NPM_TOKEN}, and set the variable in your CI secrets.
  • Use npm login or npm config fix instead of hand-editing when you are unsure how a registry address should look.
  • Pin the npm version in CI and read the release notes before you move to a new major version.

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.