Debugging Highlights Summary

Every highlight bullet from the 8 pages in this section, gathered on one page and grouped by the page it came from.

Debugging Node.js Production Issues

• Production debugging trades interactivity for scale - you observe signals, you rarely attach a debugger live
• Every Node.js production failure narrows to one of a small set of root categories: CPU-bound blocking, memory growth, unresolved async work, or resource exhaustion
• A symptom (latency, restarts, OOM) is not a diagnosis - the same symptom maps to several different causes
• The fastest path to root cause is narrowing scope before forming a hypothesis, not the reverse

Debugging Basics

• node --inspect attaches Chrome DevTools to any Node process
• Breakpoints in TypeScript need source maps
• NODE_OPTIONS enables inspect in npm scripts
• Reproduce production bugs with matching Node version and data volume

Memory Leak Hunt

• Compare heap snapshots taken minutes apart to find growing retained objects
• Event listeners, closures, and global caches are common leak sites
• clinic heapprofiler shows allocation stacks under load
• Reproduce with production-like request rate and payload size

Promise That Never Settles

• A Promise with no resolve/reject hangs forever
• Missing await leaves errors as unhandled rejections
• Dangling DB transactions block pool slots
• Always use timeouts on external I/O

Event-Loop Stall Incident

• CPU-bound sync work blocks the entire event loop
• p99 latency spikes while CPU pegs on few cores
• Move parse/compress/crypto to workers or streaming
• --trace-event-categories v8 and clinic doctor find stalls

Connection Pool Exhaustion

• Unreleased clients and missing await exhaust pg pools
• Postgres max_connections is a hard cluster limit
• Pool size times pod count must fit database budget
• Use pool metrics and statement timeouts

Unhandled Rejection Production Outage

• Unhandled Promise rejections can crash Node or leave corrupt state
• Node 24 still requires explicit handling of async errors
• Register unhandledRejection and uncaughtException handlers at boot
• Policy: log + exit non-zero for API processes after draining

Debugging Best Practices

• Reproduce before you tune production blindly
• Structured logs with requestId beat printf in prod
• Strict unhandled rejection policy in CI
• Health checks must reflect event-loop and pool state

pbqrthvqrf.vb|ptvb796|202607