npm .npmrc _authToken Not Expanded - Fix Literal ${TOKEN} in CI

npm expands ${VAR} in .npmrc from the environment at runtime. If the variable is not set in the job (or is misnamed), npm sends the literal placeholder as the token and the registry rejects it.

What this error means

A private install/publish fails auth even though .npmrc has an _authToken=${NPM_TOKEN} line. The registry returns 401/403 because the placeholder was never expanded - the env var is missing, mis-cased, or the .npmrc npm read is a different one than you edited.

# .npmrc
//registry.npmjs.org/:_authToken=${NPM_TOKEN}

# job has no NPM_TOKEN set, so npm sends the literal string:
npm error code E401
npm error Incorrect or missing password.

Common causes

The env var is unset or misnamed in CI

${NPM_TOKEN} only expands if NPM_TOKEN exists in the job environment. A missing secret, a typo, or wrong casing leaves the placeholder literal.

npm read a different .npmrc

npm merges project, user, and global .npmrc. The token line you added may sit in a file npm is not reading for this command, so the effective config has no token.

The variable was masked but never exported into npm’s env

A secret defined only at one scope (e.g. not exported to the step running npm) is not visible for expansion.

How to fix it

Set the env var the placeholder names

Provide the secret in the job env using the exact name .npmrc expands.

# GitHub Actions
env:
  NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
# .npmrc line must reference the same name:
# //registry.npmjs.org/:_authToken=${NPM_TOKEN}

Confirm which .npmrc is in effect

1. Run npm config ls -l (or npm config get userconfig) to see the effective config and which files are read.
2. Put the registry/_authToken line in the project .npmrc that the install actually uses.
3. Verify the secret is exposed to the step running npm, not just defined elsewhere.

How to prevent it

• Match the .npmrc ${VAR} name to the job env var exactly.
• Generate CI .npmrc from secrets; never commit literal tokens.
• Verify the effective .npmrc with npm config ls -l when auth fails.

Related guides