What are the basics of debugging Node.js applications?

Direct answer

Use node --inspect for breakpoints, read stack traces from errors, reproduce with minimal scripts, and distinguish sync throws vs unhandled promise rejections — combine with logging and NODE_OPTIONS for local dev.

Node debugging spans runtime inspection (Chrome DevTools / VS Code), printf-style logs, and error semantics (where the failure surfaced vs where it originated).

Inspector — node --inspect-brk app.mjs; attach VS Code "JavaScript Debug Terminal".
Stack traces — read err.stack; use Error.captureStackTrace for custom errors sparingly.
REPL — node then require/import module under test (Q17).
Environment — NODE_DEBUG=module for low-level traces; DEBUG=* for some libraries.

Symptom	First check
Hang / no response	Missing res.end(), open DB connection, deadlock
ECONNREFUSED	Wrong host/port, service not running (Postgres 5433)
SyntaxError in JSON import	Trailing comma, invalid file — validate with jq
Unhandled rejection	Missing await or .catch on Promise chain

debug-helper.mjs

process.on("unhandledRejection", (reason) => {
  console.error("Unhandled rejection:", reason);
});

function wrapHandler(fn) {
  return async (req, res) => {
    try {
      await fn(req, res);
    } catch (err) {
      console.error(err.stack);
      if (!res.headersSent) {
        res.writeHead(500, { "Content-Type": "application/json" });
        res.end(JSON.stringify({ error: "Internal Server Error" }));
      }
    }
  };
}