Node.js Reference ยท CLI Flags
Node.js --trace-warnings and --trace-deprecation
Reference for node --trace-warnings, --trace-deprecation, --throw-deprecation and --no-deprecation: find where a warning comes from and control what happens.
Node.js prints warnings (such as DeprecationWarning or MaxListenersExceededWarning) as a single line, followed by a hint to rerun with a tracing flag. That one line rarely says which of your files triggered it. --trace-warnings adds the stack trace to every warning, and --trace-deprecation does the same for deprecation warnings only.
Two sister flags change what a deprecation does: --throw-deprecation turns it into a thrown exception, which is useful in CI, and --no-deprecation hides deprecation warnings completely.
// shell: node --trace-warnings app.js
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
// shell
node --trace-warnings <script>
node --trace-deprecation <script>
node --throw-deprecation <script>
node --no-deprecation <script>
node --pending-deprecation <script>
| Name | Description |
|---|---|
--trace-warnings |
Prints the stack trace of every warning. |
--trace-deprecation |
Prints the stack trace of deprecation warnings only. |
--throw-deprecation |
Throws deprecation warnings as errors (they surface as an uncaught exception). |
--no-deprecation |
Silences all deprecation warnings. |
--pending-deprecation |
Also reports APIs that are scheduled for deprecation. Useful in CI to get ahead of future breakage. |
Returns: nothing. The tracing flags only change what is written to stderr.
Edge cases: each deprecation code (such as DEP0005) is reported only once per process, so the second call to the same API prints nothing. Warnings raised from inside node_modules are not always shown for runtime deprecations; --trace-deprecation still reveals them when they do fire.
Usage notes
- Read the stack from the first non-
node:frame. In the example, the firstwarn.cjsline is the call you need to change; frames starting withnode:internalare just the loader. - A warning is not an error. The program keeps running (the output
program ran, length 2still appears), unless you add--throw-deprecation. - Use
--throw-deprecationin test and CI runs to fail fast when a dependency starts using a deprecated API. - Do not use
--no-deprecationas a fix. It hides warnings that tell you a future upgrade will break something. Prefer--disable-warning=DEP0005to silence one specific, understood warning. - Programmatic access:
process.on('warning', handler)receives each warning object (name,message,code,stack) so you can log it with your own logger. Seeprocess.emitWarning(). - Related:
--trace-uncaughtprints the stack where a thrown non-error value was created, and--trace-exitshows whereprocess.exit()was called from. - Set it for child processes with
NODE_OPTIONS; both tracing flags are allowed there. - Messages and codes are not API. Match on
warning.coderather than on text.