Reading the Official Docs & Diagnostics
When Node.js behavior surprises you, the official API reference and built-in diagnostic flags beat Stack Overflow answers from outdated majors.
//
Search across all documentation pages
When Node.js behavior surprises you, the official API reference and built-in diagnostic flags beat Stack Overflow answers from outdated majors.
Quick-reference recipe card - copy-paste ready.
node --help # CLI flags
node -p "process.versions" # exact versions in this binary
NODE_DEBUG=module node app.mjs # trace module loading
node --trace-warnings app.mjs # show warning stack traces
node --report-on-fatalerror app.mjs # write diagnostic report on crashWhen to reach for this:
exports or imports// diagnostics.ts - enable useful warnings in development
import { emitWarning } from 'node:process';
if (process.env.NODE_ENV !== 'production') {
// Surface deprecation warnings with stacks
process.on('warning', (w) => {
console.warn('[node-warning]', w.name, w.message);
if (w.stack) console.warn(w.stack);
});
}
export function writeDiagnosticReport(reason: string): string {
const report = process.report?.writeReport(reason);
return report ?? 'report-unavailable';
}# Run with trace flags during local reproduction
NODE_OPTIONS="--trace-warnings --trace-deprecation" node --import tsx src/main.ts
# Module resolution confusion
NODE_DEBUG=esm node src/main.ts 2>&1 | head -40What this demonstrates:
process.on('warning') captures deprecations before they become hard failuresNODE_OPTIONS centralizes flags across npm scripts and containersNODE_DEBUG=esm logs ESM loader decisions - invaluable for exports field bugsprocess.report.writeReport() produces JSON for post-mortemsnodejs.org/api are versioned - select v24.18.0 to match your runtime.--report-on-fatalerror, SIGUSR2) capture heap, stack, libuv handles, and environment.NODE_DEBUG=http, net, module, esm).nodejs/node CHANGELOG) document breaking changes per minor/patch.| Symptom | First resource | Flag / tool |
|---|---|---|
| Module not found | node:module docs, package.json exports | NODE_DEBUG=module |
| Deprecation warning | Release notes for your target version | --trace-deprecation |
| Memory growth | node:process memoryUsage | --heapsnapshot-near-heap-limit=3 |
| Event loop lag | Event Loop docs | monitorEventLoopDelay |
| HTTP oddities | node:http docs | NODE_DEBUG=http |
import { styleText } from 'node:util';
// Node 24 util.styleText for readable CLI diagnostics output
console.log(styleText('yellow', 'Warning:'), 'Check nodejs.org/api/v24 for API changes');nodejs.org/api/v24.x.--trace-deprecation in CI.nodejs/node issues and CHANGELOG.NODE_DEBUG in production - verbose logs leak internals and cost I/O. Fix: reproduce locally with debug, use structured logging in prod.engines when docs assume a version - examples may use APIs absent on your runtime. Fix: align local, CI, and prod on 24.18.0.| Alternative | Use When | Don't Use When |
|---|---|---|
| MDN (for Web APIs) | fetch, URL, TextEncoder | Node-specific modules like node:fs |
| Package README | Library-specific behavior | Core runtime semantics |
node --experimental-print-required-tla | Top-level await ordering bugs | General HTTP debugging |
| APM / OpenTelemetry | Production latency distributions | Understanding a single API signature |
Visit https://nodejs.org/docs/latest-v24.x/api/index.html or run node -p "process.version" and match the major in the version picker.
An environment variable enabling internal Node tracing. Common values: module, esm, http, net. Output goes to stderr.
Run with node --trace-warnings or set NODE_OPTIONS=--trace-warnings.
A JSON file with stack, heap, uv handles, and environment snapshot. Triggered on fatal errors or via SIGUSR2 when configured.
In the Node.js CHANGELOG on GitHub and in release blog posts for each major. Search for "Semver-Major".
NODE_DEBUG=esm shows import decisions. Also read package.json exports.
Search issues first. Open a new issue with reproduction version (node -v), platform, and minimal repro script.
Treats pending deprecations as active warnings - useful when preparing for the next major upgrade.
Run the same script on both versions with fnm exec 22.23.1 -- node script.mjs and fnm exec 24.18.0 -- node script.mjs.
node:fetch is documented under Web-compatible APIs. MDN covers API shape; Node docs cover Node-specific options.
import { writeHeapSnapshot } from 'node:v8';
writeHeapSnapshot(`./heap-${Date.now()}.heapsnapshot`);https://nodejs.org/en/blog/vulnerability and the nodejs-sec mailing list.
Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.
Reviewed by Chris St. John·Last updated Jul 16, 2026