Skip to content
Tutorials Center
My learning

Topics

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.

NODE
// shell: node --trace-warnings app.js

Try it

Node.js Where did this warning come from?

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.

Node.js Deprecations: show, trace, throw or hide

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

NODE
// 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 first warn.cjs line is the call you need to change; frames starting with node:internal are just the loader.
  • A warning is not an error. The program keeps running (the output program ran, length 2 still appears), unless you add --throw-deprecation.
  • Use --throw-deprecation in test and CI runs to fail fast when a dependency starts using a deprecated API.
  • Do not use --no-deprecation as a fix. It hides warnings that tell you a future upgrade will break something. Prefer --disable-warning=DEP0005 to 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. See process.emitWarning().
  • Related: --trace-uncaught prints the stack where a thrown non-error value was created, and --trace-exit shows where process.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.code rather than on text.