The punycode deprecation trace is not useful

[glenjamin]

Version

v24.13.1

Platform

Darwin <hostname> 24.6.0 Darwin Kernel Version 24.6.0: Wed Nov  5 21:34:00 PST 2025; root:xnu-11417.140.69.705.2~1/RELEASE_ARM64_T8132 arm64

Subsystem

No response

What steps will reproduce the bug?

In a project that uses punycode somewhere.

NODE_OPTIONS='--trace-deprecation' npm t

or more concretely (although obviously in this case it's trivial to identify the source):

npm init -y
npm i psl@1.8.0
node --trace-deprecation -e 'require("psl")'

How often does it reproduce? Is there a required condition?

always

What is the expected behavior? Why is that the expected behavior?

I would expect a trace telling me which package/file is requiring punycode

What do you see instead?

What I actually get is

(node:49440) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
    at node:punycode:7:10
    at BuiltinModule.compileForInternalLoader (node:internal/bootstrap/realm:398:7)
    at BuiltinModule.compileForPublicLoader (node:internal/bootstrap/realm:337:10)
    at loadBuiltinModule (node:internal/modules/helpers:125:7)
    at loadBuiltinWithHooks (node:internal/modules/cjs/loader:1195:15)
    at Module._load (node:internal/modules/cjs/loader:1285:48)
    at TracingChannel.traceSync (node:diagnostics_channel:328:14)
    at wrapModuleLoad (node:internal/modules/cjs/loader:245:24)
    at Module.require (node:internal/modules/cjs/loader:1548:12)
    at require (node:internal/modules/helpers:152:16)

Additional information

I note that #56632 will reduce the number of times this warning appears, so perhaps that's good enough - but in general it seems reasonable to say that using --trace-deprecation should actually trace the usage of deprecated code.

[MikeMcC399]

This appears to be a regression introduced through #60991 in v24.13.1. I checked on several other key Node.js versions, and none of them triggered using psl@1.8.0. (The issue was actually fixed in psl@1.10.0.)

Node.js	Result
20.20.0	no deprecation
22.22.0	no deprecation
24.0.0	no deprecation
24.13.0	no deprecation
24.13.1	at node:punycode:7:10
25.6.1	no deprecation

Also there is a documentation mismatch, where DEP00040 is declared as a Runtime deprecation (all code). The v24.13.1 code however attempts to apply an Application deprecation (non-node_modules code only). Edit: submitted #61916 to update the documentation.

node/lib/punycode.js

Lines 6 to 13 in a087002

	if (!isInsideNodeModules()) {
	process.emitWarning(
	'The `punycode` module is deprecated. Please use a userland ' +
	'alternative instead.',
	'DeprecationWarning',
	'DEP0040',
	);
	}

---

#61724 appears also to be related to changes introduced in #60991

[MikeMcC399]

I'm also seeing this issue with https://github.com/eslint/eslint/docs and Node.js 24.13.1.

[MikeMcC399]

So the bug is not really that the deprecation trace is unhelpful, even though this is the way it appears.

In fact there should be no deprecation warning at all in this situation where punycode is being using inside node_modules and Node.js is >=22.14.0.

(For Node.js 20.x there should be no deprecation warning at all for punycode, wherever it is being used, unless node is run with the --pending-deprecation option.)

[glenjamin]

My intention when raising this bug was that where the deprecation warning is being produced with a trace, the trace should be readable.

It does appear that you've found another related bug that the deprecation warning is being shown in scenarios where it shouldn't - but even when it appears correctly the trace is still wrong.

I suppose that's less of an issue when the warning is correctly treated as an Application warning, as a grep punycode will likely locate it correctly

[MikeMcC399]

@glenjamin

My apologies for mixing up the issues! Also apologies for adding a confusingly incorrect comment here which I deleted and have replaced with this one!

---

The deprecation warning should not appear for the repro steps you provided, which was using an example where punycode was being called from inside node_modules.

In the following example, where there is no node_modules or package manager involved, a deprecation warning should be produced:

cd $(mktemp -d)
cat > index.js <<EOT
const punycode = require('node:punycode');
EOT
node --trace-deprecation index.js

In the last line of the logs, it does show the source of the const punycode = require('node:punycode'); call which is

at Object.<anonymous> (/tmp/tmp.qCUHkKm0YQ/index.js:1:18)

So it does seem that the problem boils down to Node.js incorrectly emitting a deprecation warning when node:punycode is used inside node_modules. I will come back to this issue after the documentation PR #61916 has been fully approved and merged, so that there is a solid reference to describe this issue.

Logs

Node.js 21.0.0 - 25.6.1

$ node --trace-deprecation index.js
(node:4802) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
    at node:punycode:7:10
    at BuiltinModule.compileForInternalLoader (node:internal/bootstrap/realm:398:7)
    at BuiltinModule.compileForPublicLoader (node:internal/bootstrap/realm:337:10)
    at loadBuiltinModule (node:internal/modules/helpers:125:7)
    at loadBuiltinWithHooks (node:internal/modules/cjs/loader:1201:15)
    at Module._load (node:internal/modules/cjs/loader:1253:50)
    at wrapModuleLoad (node:internal/modules/cjs/loader:255:19)
    at Module.require (node:internal/modules/cjs/loader:1555:12)
    at require (node:internal/modules/helpers:152:16)
    at Object.<anonymous> (/tmp/tmp.qCUHkKm0YQ/index.js:1:18)

[glenjamin]

I did another repro against Node 24 and 25

Setup

set dir $(mktemp -d)
cd $dir
echo 'require("punycode")' > index.js
echo 'require("punycode")' > node_modules/dep/index.js
echo 'require("dep")' > via-dep.js

Node v25.6.1, behaves as expected

> mise exec node@25 -- node --trace-deprecation index.js
(node:45150) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
    at node:punycode:7:10
    at BuiltinModule.compileForInternalLoader (node:internal/bootstrap/realm:398:7)
    at BuiltinModule.compileForPublicLoader (node:internal/bootstrap/realm:337:10)
    at loadBuiltinModule (node:internal/modules/helpers:125:7)
    at loadBuiltinWithHooks (node:internal/modules/cjs/loader:1201:15)
    at Module._load (node:internal/modules/cjs/loader:1292:48)
    at wrapModuleLoad (node:internal/modules/cjs/loader:255:19)
    at Module.require (node:internal/modules/cjs/loader:1555:12)
    at require (node:internal/modules/helpers:152:16)
    at Object.<anonymous> (/private/var/folders/0y/vtlpbcf55j1_jvbs92x2fsrh0000gn/T/tmp.vuFPDyJLQW/index.js:1:1)

Node v24.13.1, missing path to user code

> mise exec node@24 -- node --trace-deprecation index.js
(node:45246) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
    at node:punycode:7:10
    at BuiltinModule.compileForInternalLoader (node:internal/bootstrap/realm:398:7)
    at BuiltinModule.compileForPublicLoader (node:internal/bootstrap/realm:337:10)
    at loadBuiltinModule (node:internal/modules/helpers:125:7)
    at loadBuiltinWithHooks (node:internal/modules/cjs/loader:1195:15)
    at Module._load (node:internal/modules/cjs/loader:1285:48)
    at TracingChannel.traceSync (node:diagnostics_channel:328:14)
    at wrapModuleLoad (node:internal/modules/cjs/loader:245:24)
    at Module.require (node:internal/modules/cjs/loader:1548:12)
    at require (node:internal/modules/helpers:152:16)

And via node_modules

Node v24.13.1, shows trace and still missing path

> mise exec node@24 -- node --trace-deprecation via-dep.js
(node:45387) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
    at node:punycode:7:10
    at BuiltinModule.compileForInternalLoader (node:internal/bootstrap/realm:398:7)
    at BuiltinModule.compileForPublicLoader (node:internal/bootstrap/realm:337:10)
    at loadBuiltinModule (node:internal/modules/helpers:125:7)
    at loadBuiltinWithHooks (node:internal/modules/cjs/loader:1195:15)
    at Module._load (node:internal/modules/cjs/loader:1285:48)
    at TracingChannel.traceSync (node:diagnostics_channel:328:14)
    at wrapModuleLoad (node:internal/modules/cjs/loader:245:24)
    at Module.require (node:internal/modules/cjs/loader:1548:12)
    at require (node:internal/modules/helpers:152:16)

Node v25.6.1, no output, as expected

> mise exec node@25 -- node --trace-deprecation via-dep.js

I then did a bit of bisecting of releases and found that the frame is missing in 25.5.0, but present in 25.6.0

Here's the output, including a console.log(process.version) at the start of index.js.

> mise exec node@25.5 -- node --trace-deprecation index.js
v25.5.0
(node:58405) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
    at node:punycode:7:10
    at BuiltinModule.compileForInternalLoader (node:internal/bootstrap/realm:398:7)
    at BuiltinModule.compileForPublicLoader (node:internal/bootstrap/realm:337:10)
    at loadBuiltinModule (node:internal/modules/helpers:125:7)
    at loadBuiltinWithHooks (node:internal/modules/cjs/loader:1194:15)
    at Module._load (node:internal/modules/cjs/loader:1284:48)
    at TracingChannel.traceSync (node:diagnostics_channel:328:14)
    at wrapModuleLoad (node:internal/modules/cjs/loader:245:24)
    at Module.require (node:internal/modules/cjs/loader:1547:12)
    at require (node:internal/modules/helpers:152:16)

> mise exec node@25.6.0 -- node --trace-deprecation index.js
v25.6.0
(node:58385) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
    at node:punycode:7:10
    at BuiltinModule.compileForInternalLoader (node:internal/bootstrap/realm:398:7)
    at BuiltinModule.compileForPublicLoader (node:internal/bootstrap/realm:337:10)
    at loadBuiltinModule (node:internal/modules/helpers:125:7)
    at loadBuiltinWithHooks (node:internal/modules/cjs/loader:1200:15)
    at Module._load (node:internal/modules/cjs/loader:1290:48)
    at wrapModuleLoad (node:internal/modules/cjs/loader:255:19)
    at Module.require (node:internal/modules/cjs/loader:1553:12)
    at require (node:internal/modules/helpers:152:16)
    at Object.<anonymous> (/private/var/folders/0y/vtlpbcf55j1_jvbs92x2fsrh0000gn/T/tmp.vuFPDyJLQW/index.js:2:1)

Looking at the 25.6.0 changelog, it looks like this PR is probably the one that fixes the trace: #61479

It looks like that's slated for 24.14 according to #61924 - so this would be resolved in the LTS branch once that's out.

[MikeMcC399]

@glenjamin
Thanks for the additional tests and information! We'll see what remains to be fixed after the next releases!

[MikeMcC399]

@glenjamin

It looks like that's slated for 24.14 according to #61924 - so this would be resolved in the LTS branch once that's out.

Node.js 24.14.0 has now been released. I did a quick check and it looks like it is resolved as you predicted.

[glenjamin]

Great, thanks!

I'll close this out then