Node.js offers three deprecation flags. Pending deprecation turns on early warning for APIs not yet deprecated at runtime. Trace deprecation prints stack traces so you can find the caller. Throw deprecation turns warnings into errors. Use them in a test run before moving to a new Node major.
The three flags
The Node.js command line documentation describes each one.
| Flag | Documented behavior |
|---|---|
| Pending deprecation | Emits pending deprecation warnings, off by default, also enabled by an environment variable |
| Trace deprecation | Prints stack traces for deprecations |
| Throw deprecation | Throws errors for deprecations |
The documentation says pending deprecations are generally identical to runtime deprecations except that they are turned off by default. They are used as a selective early warning mechanism that developers can use to detect deprecated API usage. The environment variable version is useful in CI, where passing a flag through every tool is awkward.
When to use which
Start with trace. A plain deprecation warning tells you what was called, but not who called it. In a project with many dependencies, the caller is often a package you did not write. The stack trace points to the file and often the package.
node --trace-deprecation app.js
Add pending to see what is coming, a release or two ahead of the runtime warning.
node --pending-deprecation --trace-deprecation app.js
Use throw last. It makes the first deprecation fail the process, which is excellent as a gate once your own code is clean, and painful before that.
node --throw-deprecation app.js
A rollout that does not break the team
- Run the test suite with the pending and trace flags and write the output to a file.
- Group warnings by origin: your code, a direct dependency, a transitive one.
- Fix your own code. Open upgrade tickets for direct dependencies.
- Re-run until only third party warnings remain, and list those with owners.
- Enable the throw flag for tests that exercise only your own code paths, or for a dedicated job, rather than the whole suite at first.
- Move to the next Node major in a branch and run again.
Choosing the Node version to move to
The Node.js releases page explains that, up to Node.js 26, even numbered releases move to long-term support status and odd numbered ones become unsupported after six months. Starting with Node.js 27 the cycle is annual, and every major version moves to LTS after its six month Current phase. LTS typically guarantees critical bug fixes for a total of 30 months. Read the live page before choosing a target, since schedules are updated.
For production, pick a release that is in a supported long-term phase, and make the flags part of the move to it.
What these flags do not catch
They only report what your tests execute. Dead code paths, rarely used admin screens and error handlers can still call a removed API. Cover them with at least a smoke test, or search for known removed APIs in the release notes of the target version.
Quick check
Which flag tells me which package is calling a deprecated API?
The trace flag, because it prints a stack trace for the deprecation.
Should I run production with the throw flag?
Usually no. Use it in tests, where a failure is cheap, and not in a live service.
Safeguard scans your npm dependencies for known vulnerabilities and shows which are reachable. Try the free scan at gold.safeguard.sh/scan.
Sources
Last reviewed: 19 October 2026.
