In Node.js 24, what is a process warning, how do you capture one with process.on('warning'), and which flags silence or escalate warnings?
answer
- an Error object that is not thrown
- Deprecation, Experimental, MaxListeners names
- the default printer is a listener
- filter by code or by type
- turn deprecations into exceptions
basics
~20 sA process warning is an Error-shaped notice, such as a DeprecationWarning, that Node emits on the 'warning' event and prints to stderr without stopping the process. --no-warnings hides printing, --disable-warning filters by code or type, --throw-deprecation escalates deprecations.
solid answer
~40 sNode emits process warnings for practices that are not errors but deserve attention: a deprecated API (`DeprecationWarning` with a `DEP` code), an experimental feature (`ExperimentalWarning`), too many listeners on one emitter, an out-of-range timer delay. Each is an `Error` object with `name`, `message` and `stack`, which `process.emitWarning()` delivers to `process.on('warning')` on a later tick; it is never thrown and never ends the process. The default stderr output is itself a `'warning'` listener Node installs at start-up, so `--no-warnings` or `NODE_NO_WARNINGS=1` removes the printing while your own listener still fires. `--disable-warning=DEP0025` or `--disable-warning=ExperimentalWarning` suppresses one code or type, a flag stable since v24.20.0. `--trace-warnings` adds stack traces, `--redirect-warnings=file` writes to a file, and `--throw-deprecation` throws deprecations as errors. Your own code emits warnings with `process.emitWarning()`.
code
javascript · 11 lines// warnings.cjs (run with: node --no-warnings warnings.cjs)
process.on('warning', (warning) => {
console.error(JSON.stringify({
level: 'warn', name: warning.name, code: warning.code, msg: warning.message,
}));
});
process.emitWarning('Cache size above 10,000 entries', {
type: 'CapacityWarning',
code: 'APP_CACHE_SIZE',
});go deeper
Recall that a warning is printed to stderr but does not stop the process, and that DeprecationWarning and ExperimentalWarning are the common ones.
Explain the path from process.emitWarning() to the 'warning' event and the default printer, and what each flag changes along that path.
Show how to turn warnings into structured log events, silence one code without losing the rest, and use --throw-deprecation to catch deprecated APIs in CI.
Decide the fleet's warning policy: what is logged, what is suppressed and by whom, and how deprecations are budgeted before each runtime upgrade.
## What counts as a process warning A **process warning** is Node.js telling you about an exceptional condition that is not part of normal error handling: a bad coding practice that could lead to poor performance, bugs or security holes. A warning is an `Error` object with a `name`, a `message` and a `stack`, but it is **not thrown**, so `try...catch` never sees it and the process carries on. The names Node uses most often: - `DeprecationWarning`: use of a deprecated API or feature; Node's own deprecation warnings carry a `code` such as `DEP0025`. - `ExperimentalWarning`: use of a feature outside the usual semantic-versioning and long-term support guarantees. - `MaxListenersExceededWarning`: too many listeners for one event on an `EventEmitter` or `EventTarget`, often a sign of a leak. - `TimeoutOverflowWarning`, `TimeoutNegativeWarning` and `TimeoutNaNWarning`: a bad delay passed to `setTimeout()` or `setInterval()`. - `UnsupportedWarning`: an option or feature that will be ignored rather than treated as an error. The docs say new warning types can be added at any time, so code should not assume the list is complete. ## How a warning travels 1. Your code, or Node itself, calls `process.emitWarning(warning, options)`, where `options` can carry `type`, `code` and `detail`. 2. `process.emitWarning()` builds the warning object and emits it on a **later tick** using `process.nextTick`, not before the call returns. A few of Node's internal deprecations use a synchronous variant instead. 3. Every `process.on('warning', listener)` receives the object. 4. One of those listeners is Node's own printer, installed at start-up unless warnings are disabled. It writes a line such as `(node:4242) [DEP0025] DeprecationWarning: ...` to stderr, followed once per process by a hint to rerun with `--trace-warnings` or `--trace-deprecation`. Because `process.emitWarning()` defers delivery, a warning emitted with it just before `process.exit()` can be lost: the exit happens before the tick that would deliver it. ## Flags and environment variables | Setting | Effect | |---|---| | `--no-warnings` or `NODE_NO_WARNINGS=1` | Node's printer is not installed; the `'warning'` event still fires for your listeners | | `--disable-warning=code-or-type` | The printer skips warnings whose `code` or name matches, for example `DEP0025` or `ExperimentalWarning` | | `--no-deprecation` | Suppresses reporting of deprecation warnings | | `--trace-warnings` | Printed warnings include the full stack trace | | `--trace-deprecation` | Printed deprecation warnings include the stack trace | | `--throw-deprecation` | Deprecation warnings are thrown as errors | | `--redirect-warnings=file` | Warnings are appended to a file instead of stderr | All of these flags are allowed in `NODE_OPTIONS`, so a service can set them once in its environment. `--disable-warning` was added in Node 21.3.0 and 20.11.0 and marked stable in 24.20.0. ## Emitting your own warnings `process.emitWarning()` accepts either a string or an `Error`. With a string, an options object sets the details: - `type` names the warning, defaulting to `'Warning'`; - `code` is a unique identifier for that warning, which `--disable-warning` can match; - `detail` adds text printed after the message; - `ctor` limits the generated stack trace, defaulting to `process.emitWarning` itself. Giving every warning a stable `code` is what lets operators silence one known warning without hiding the rest. Passing `type: 'DeprecationWarning'` opts a library's own deprecations into `--no-deprecation`, `--trace-deprecation` and `--throw-deprecation`, which only act on warnings with that name. ## Using warnings in production - **Route them into your logs.** A `'warning'` listener that writes `name`, `code` and `message` as structured fields, combined with `--no-warnings` so the default line is not printed twice, turns warnings into searchable events. - **Silence narrowly.** Hiding one known `ExperimentalWarning` with `--disable-warning` keeps every other signal; a blanket `--no-warnings` without a listener throws away the deprecation notices you need before the next runtime upgrade. - **Fail CI on deprecations.** Running the test suite with `--throw-deprecation` turns each use of a deprecated API into a thrown error, so it is fixed before an upgrade removes the API. - **Read `MaxListenersExceededWarning` as a lead, not a verdict.** It is often a leak; finding the leak belongs to the material on heap limits and leaks. - **Emit your own sparingly.** `process.emitWarning()` with a `type` and a `code` is the right channel for a library that wants to warn its users without throwing.
- How would you make a Node.js test run fail whenever code uses a deprecated API?Run the tests with `--throw-deprecation`, for example through `NODE_OPTIONS`, which accepts the flag. Deprecation warnings are then thrown as errors instead of printed, so the failing test points at the call. `--trace-deprecation` is the gentler option when you only want the stack trace of each use.
- Why can a warning emitted right before process.exit() never appear?`process.emitWarning()` does not emit synchronously: it schedules the `'warning'` event with `process.nextTick`. If `process.exit()` runs before that tick, neither Node's printer nor your listener receives the warning. Setting `process.exitCode` and letting the process end naturally gives the tick a chance to run.
- A DeprecationWarning means the API has already stopped working.
- --no-warnings stops the 'warning' event from firing.
- Warnings are thrown, so a try/catch around the call catches them.
- The only way to hide one noisy warning is --no-warnings.
- process.emitWarning() delivers the warning before it returns.
Assumes Node.js 24; --disable-warning was added in v21.3.0 and v20.11.0 and marked stable in v24.20.0.