Maaz Zindani

Loading the index…

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

npm says it failed to replace ${NPM_TOKEN} in the config

Errornpm ERR! Failed to replace env in config: ${NPM_TOKEN}

Short answer

npm replaces ${NPM_TOKEN} in .npmrc with the value of an environment variable of that name when it starts. If the variable is not set in the process that runs npm, the replacement fails. Set the variable in that exact shell, CI step or Docker build, then run npm again.

  • Applies to npm 10, npm 11, Node.js 22, GitHub Actions, Docker
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check whether the variable exists in the shell that runs npm. Print only whether it is set, not the token.

    [ -n "$NPM_TOKEN" ] && echo set || echo NOT SET
    grep -n "NPM_TOKEN" .npmrc ~/.npmrc
  2. 2Match what you see, then jump to its fix

    1. 1The check above prints NOT SETThe variable is not set where npm runsFix
    2. 2Fails in GitHub Actions or another CI, works on your laptopThe CI job does not pass the secret into the stepFix
    3. 3The variable is set but npm still fails, or the token is rejected afterwardsThe .npmrc line itself is written wronglyFix

What does the error look like?

  • npm ERR! Failed to replace env in config: ${NPM_TOKEN}
  • npm error Failed to replace env in config: ${NPM_TOKEN}

Cause 1 of 3

The variable is not set where npm runs

1Check

npm fills ${NPM_TOKEN} from the environment of its own process. A variable exported in another terminal, or in a profile file that a non-login shell does not read, is not there.

env | grep -c '^NPM_TOKEN='

2Fix

Export the variable in the same shell before the command, or pass it for one command.

export NPM_TOKEN=your-token-here
npm install

3Verify

npm installs without the replace error.

npm install

Confirmed by docs.npmjs.com

Did this fix it?

Cause 2 of 3

The CI job does not pass the secret into the step

1Check

A secret is not an environment variable until the job maps it. The npm CI guide creates the variable from the secret in the step's env block.

grep -n -B2 -A6 "npm" .github/workflows/*.yml

2Fix

Add the secret to the step that runs npm, using the same name as in .npmrc.

- run: npm ci
  env:
    NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

3Verify

Re-run the job and watch the install step.

git push

Confirmed by docs.npmjs.com

Did this fix it?

Cause 3 of 3

The .npmrc line itself is written wrongly

1Check

The documented line keeps the literal text ${NPM_TOKEN} in the file and puts the registry prefix in front of it. The token value must never be pasted into the file.

grep -n "_authToken" .npmrc

2Fix

Use the documented form, with the name matching the variable exactly.

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

3Verify

Run the install with the variable set.

npm install

Confirmed by docs.npmjs.com

Did this fix it?

How do I stop it coming back?

  • Keep the token only in the CI secret store and local environment, never in git.
  • In Docker, pass the value at build time from the CI job instead of copying a filled .npmrc into an image layer.
  • Use a read-only granular token for installs.
  • Add a first CI step that fails with a clear message when the variable is empty.

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

Next step

Want this handled for good?

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