npm says it failed to replace ${NPM_TOKEN} in the config
npm 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.
Fix it fast
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 ~/.npmrc2Match what you see, then jump to its fix
- 1
The check above prints NOT SETThe variable is not set where npm runsFix - 2
Fails in GitHub Actions or another CI, works on your laptopThe CI job does not pass the secret into the stepFix - 3
The variable is set but npm still fails, or the token is rejected afterwardsThe .npmrc line itself is written wronglyFix
- 1
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 install3Verify
npm installs without the replace error.
npm installConfirmed by docs.npmjs.com
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/*.yml2Fix
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 pushConfirmed by docs.npmjs.com
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" .npmrc2Fix
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 installConfirmed by docs.npmjs.com
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Back end
npm install or publish stops with E401 and a password message
npm ERR! Incorrect or missing password.
E401 means the registry did not accept the login npm sent.
3 causes, each with a fixBack end
Node.js in Docker Compose cannot reach MySQL on 127.0.0.1:3306
Error: connect ECONNREFUSED 127.0.0.1:3306
Inside a container, 127.0.0.1 is that container, not MySQL.
3 causes, each with a fixBack end
A Docker build or container says npm: not found
npm: command not found
A container only has the programs its image holds.
3 causes, each with a fixBack end
ECS task stops with exec format error on start
exec /usr/local/bin/docker-entrypoint.sh: exec format error
The container's binary was built for another CPU than the task runs on.
2 causes, each with a fixBack end
npm publish fails in GitHub Actions with ENEEDAUTH
npm error code ENEEDAUTH
ENEEDAUTH means npm has no valid login in the job.
4 causes, each with a fixBack end
Kong Gateway returns 502 'An invalid response was received from the upstream server'
upstream sent too big header while reading response header from upstream
Kong returns 502 when it cannot get a valid HTTP response from the upstream.
4 causes, each with a fix