Node "punycode module is deprecated" DEP0040 Warning - Fix in CI
Node 21+ emits [DEP0040] The punycode module is deprecated when a dependency imports the built-in punycode. It is a warning, not an error - but it clutters CI logs and, with --throw-deprecation, can fail a step.
What this error means
CI logs show (node:NNN) [DEP0040] DeprecationWarning: The punycode module is deprecated. Please use a userland alternative instead. It typically comes from a transitive dependency (e.g. an older URI/whatwg library), not your own code.
(node:12345) [DEP0040] DeprecationWarning: The `punycode` module is deprecated.
Please use a userland alternative instead.
(Use `node --trace-deprecation ...` to show where the warning was created)Diagnose it: which registry, and with what credentials?
Registry errors are resolved in a precedence chain, and the effective value is rarely the one in the file you are looking at. Scoped registries, .npmrc files at several levels, and environment variables all combine before a request is made.
# the effective, fully merged configuration
npm config list -l | grep -E "registry|_auth|always-auth"
# where each value came from
npm config get registry
npm config get @yourscope:registry
# prove the token works, independently of the install
curl -sI -H "Authorization: Bearer $NPM_TOKEN" \
"$(npm config get registry)@yourscope%2fpackage" | head -1Common causes
A transitive dependency imports the built-in punycode
An older library still requires Node’s deprecated punycode builtin. On Node 21+ that import triggers DEP0040 on every run.
A strict deprecation flag turns it fatal
Running with --throw-deprecation (or NODE_OPTIONS=--throw-deprecation) escalates the warning into a thrown error that fails the step.
How to fix it
Trace and upgrade the source dependency
Find which dependency imports punycode and upgrade it to a version that uses a userland alternative.
node --trace-deprecation node_modules/.bin/<your-cli>
# or pinpoint the dependency:
npm ls punycode
npm install <offending-parent>@latestSilence intentionally if you cannot upgrade yet
- Confirm the warning is from a third-party dependency, not your code.
- If you must quiet logs, set
NODE_NO_WARNINGS=1only where appropriate - it hides all warnings, so use sparingly. - Track the upstream issue and remove the suppression once upgraded.
How to prevent it
- Upgrade dependencies that import deprecated builtins.
- Avoid
--throw-deprecationin CI until sources are clean. - Trace deprecations with
--trace-deprecationto find the origin.