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.

Recipe

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 crash

When to reach for this:

Upgrading from Node 22 to 24 and hitting deprecated API warnings
Module resolution errors that mention exports or imports
Unclear whether behavior is a bug, breaking change, or misconfiguration
Production incidents needing a structured crash report

Working Example

// 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 -40

What this demonstrates:

process.on('warning') captures deprecations before they become hard failures
NODE_OPTIONS centralizes flags across npm scripts and containers
NODE_DEBUG=esm logs ESM loader decisions - invaluable for exports field bugs
process.report.writeReport() produces JSON for post-mortems

Deep Dive

How It Works

Official docs at nodejs.org/api are versioned - select v24.18.0 to match your runtime.
Diagnostic reports (--report-on-fatalerror, SIGUSR2) capture heap, stack, libuv handles, and environment.
Trace flags hook into Node's internal logging (NODE_DEBUG=http, net, module, esm).
Release notes on GitHub (nodejs/node CHANGELOG) document breaking changes per minor/patch.

Where to Look First

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`

TypeScript Notes

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');

Gotchas

Reading v18 docs while running v24 - API signatures and defaults change. Fix: bookmark nodejs.org/api/v24.x.
Ignoring deprecation warnings - they become hard errors in the next major. Fix: --trace-deprecation in CI.
Blog posts over release notes - third-party articles skip edge cases. Fix: search nodejs/node issues and CHANGELOG.
Enabling all NODE_DEBUG in production - verbose logs leak internals and cost I/O. Fix: reproduce locally with debug, use structured logging in prod.
Skipping engines when docs assume a version - examples may use APIs absent on your runtime. Fix: align local, CI, and prod on 24.18.0.

Alternatives

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

FAQs

How do I open docs for my exact Node version?

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.

What is NODE_DEBUG?

An environment variable enabling internal Node tracing. Common values: module, esm, http, net. Output goes to stderr.

How do I get a stack trace for warnings?

Run with node --trace-warnings or set NODE_OPTIONS=--trace-warnings.

What is a diagnostic report?

A JSON file with stack, heap, uv handles, and environment snapshot. Triggered on fatal errors or via SIGUSR2 when configured.

Where are breaking changes listed?

In the Node.js CHANGELOG on GitHub and in release blog posts for each major. Search for "Semver-Major".

How do I debug ESM vs CJS resolution?

NODE_DEBUG=esm shows import decisions. Also read package.json exports.

Is the Node.js Discord / GitHub issues appropriate?

Search issues first. Open a new issue with reproduction version (node -v), platform, and minimal repro script.

What does --pending-deprecation do?

Treats pending deprecations as active warnings - useful when preparing for the next major upgrade.

How do I compare Node 22 vs 24 behavior?

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.

Where is fetch documented?

node:fetch is documented under Web-compatible APIs. MDN covers API shape; Node docs cover Node-specific options.

Can I generate heap snapshots programmatically?

import { writeHeapSnapshot } from 'node:v8';
writeHeapSnapshot(`./heap-${Date.now()}.heapsnapshot`);

What official resource covers security releases?

https://nodejs.org/en/blog/vulnerability and the nodejs-sec mailing list.

Node.js Release & LTS Policy - version you should read docs for
Installing & Version Management - align binaries with documentation
Detecting Event-Loop Blockage - when docs point to perf_hooks
Debugging Basics - structured incident debugging

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.

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.

Recipe

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 crash

When to reach for this:

Upgrading from Node 22 to 24 and hitting deprecated API warnings
Module resolution errors that mention exports or imports
Unclear whether behavior is a bug, breaking change, or misconfiguration
Production incidents needing a structured crash report

Working Example

// 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 -40

What this demonstrates:

process.on('warning') captures deprecations before they become hard failures
NODE_OPTIONS centralizes flags across npm scripts and containers
NODE_DEBUG=esm logs ESM loader decisions - invaluable for exports field bugs
process.report.writeReport() produces JSON for post-mortems

Deep Dive

How It Works

Official docs at nodejs.org/api are versioned - select v24.18.0 to match your runtime.
Diagnostic reports (--report-on-fatalerror, SIGUSR2) capture heap, stack, libuv handles, and environment.
Trace flags hook into Node's internal logging (NODE_DEBUG=http, net, module, esm).
Release notes on GitHub (nodejs/node CHANGELOG) document breaking changes per minor/patch.

Where to Look First

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`

TypeScript Notes

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');

Gotchas

Reading v18 docs while running v24 - API signatures and defaults change. Fix: bookmark nodejs.org/api/v24.x.
Ignoring deprecation warnings - they become hard errors in the next major. Fix: --trace-deprecation in CI.
Blog posts over release notes - third-party articles skip edge cases. Fix: search nodejs/node issues and CHANGELOG.
Enabling all NODE_DEBUG in production - verbose logs leak internals and cost I/O. Fix: reproduce locally with debug, use structured logging in prod.
Skipping engines when docs assume a version - examples may use APIs absent on your runtime. Fix: align local, CI, and prod on 24.18.0.

Alternatives

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

FAQs

How do I open docs for my exact Node version?

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.

What is NODE_DEBUG?

An environment variable enabling internal Node tracing. Common values: module, esm, http, net. Output goes to stderr.

How do I get a stack trace for warnings?

Run with node --trace-warnings or set NODE_OPTIONS=--trace-warnings.

What is a diagnostic report?

A JSON file with stack, heap, uv handles, and environment snapshot. Triggered on fatal errors or via SIGUSR2 when configured.

Where are breaking changes listed?

In the Node.js CHANGELOG on GitHub and in release blog posts for each major. Search for "Semver-Major".

How do I debug ESM vs CJS resolution?

NODE_DEBUG=esm shows import decisions. Also read package.json exports.

Is the Node.js Discord / GitHub issues appropriate?

Search issues first. Open a new issue with reproduction version (node -v), platform, and minimal repro script.

What does --pending-deprecation do?

Treats pending deprecations as active warnings - useful when preparing for the next major upgrade.

How do I compare Node 22 vs 24 behavior?

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.

Where is fetch documented?

node:fetch is documented under Web-compatible APIs. MDN covers API shape; Node docs cover Node-specific options.

Can I generate heap snapshots programmatically?

import { writeHeapSnapshot } from 'node:v8';
writeHeapSnapshot(`./heap-${Date.now()}.heapsnapshot`);

What official resource covers security releases?

https://nodejs.org/en/blog/vulnerability and the nodejs-sec mailing list.

Node.js Release & LTS Policy - version you should read docs for
Installing & Version Management - align binaries with documentation
Detecting Event-Loop Blockage - when docs point to perf_hooks
Debugging Basics - structured incident debugging

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.

Reading the Official Docs & Diagnostics

Buscar en la documentación

Reading the Official Docs & Diagnostics