Debugging Basics

8 examples to get you started debugging Node.js backends - 6 basic and 2 intermediate.

Prerequisites

Node.js 24.18.0 installed locally. Chrome or Edge browser for DevTools.

node --version   # v24.18.0

Basic Examples

1. Start Inspector on Boot

node --inspect src/main.ts
# Debugger listening on ws://127.0.0.1:9229

• Open chrome://inspect -> Configure -> add localhost:9229 -> inspect
• Default port 9229; use --inspect=9230 if occupied
• Bind 0.0.0.0 only in trusted dev networks: --inspect=0.0.0.0

Related: Memory Leak Hunt - heap snapshots in DevTools

2. Break on First Line

node --inspect-brk src/main.ts

• Process pauses before user code runs - attach debugger then resume
• Useful when bug happens at module load time
• CI should not use --inspect-brk without timeout

3. debugger Statement

export function charge(amountCents: number) {
  if (amountCents < 0) {
    debugger; // execution pauses when inspector attached
    throw new Error("invalid amount");
  }
  return { charged: amountCents };
}

• Remove debugger before merge - ESLint no-debugger in CI
• Works with tsx when inspector enabled
• Prefer breakpoints in DevTools for shared code paths

4. NODE_OPTIONS in npm Scripts

{
  "scripts": {
    "dev:debug": "NODE_OPTIONS='--inspect' tsx watch src/main.ts"
  }
}

• Windows: use cross-env NODE_OPTIONS=--inspect
• tsx watch restarts process - reattach DevTools after reload
• Pair with VS Code launch.json for team standard

5. Log vs Debugger

import { inspect } from "node:util";
 
console.log(inspect({ orderId: "ord_1", meta: { retry: 2 } }, { depth: 5, colors: true }));

• console.log for production-safe correlation with requestId
• Debugger for stepping when state is unclear
• util.inspect prints nested objects readable in terminal

Related: Logging Basics - structured logs in prod

6. Print Stack Trace

function fail() {
  throw new Error("payment provider timeout");
}
 
try {
  fail();
} catch (err) {
  console.error(err instanceof Error ? err.stack : err);
}

• Error.captureStackTrace customizes stack in library code
• Log stacks server-side only - never return to API clients in prod

Intermediate Examples

7. Source Maps With TypeScript

// tsconfig.json
{
  "compilerOptions": {
    "sourceMap": true,
    "inlineSources": true
  }
}

• DevTools shows .ts lines, not transpiled .js
• tsc output + node --inspect dist/main.js for prod-like debug
• tsx handles TS directly without separate compile step

8. Attach to Running Process

# Find PID
pgrep -fl "node dist/main"
 
# Attach inspector to live process (brief pause)
kill -USR1 <pid>
# Then node logs: Debugger listening...

• SIGUSR1 enables inspect on running Node (if not started with --inspect)
• Use only in staging - attaching in prod requires runbook approval
• Combine with Event-Loop Stall Incident profiling

External Related Links

• Node.js API Documentation - Complete reference for core modules and APIs.
• Node.js Best Practices (GitHub) - Curated production best practices.
• Stack Overflow – Node.js Tag - Q&A for real-world problems.
• Node.js Cookbook, 5th Edition - Practical server-side recipes.
• Node.js Design Patterns, 4th Edition - Production-grade application patterns.

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.