Debugging Node.js Applications — Inspector, Chrome DevTools, and VS Code

console.log debugging works until your server handles 500 requests per second and you realise logging every variable doubles response time. Node.js ships with a production-grade debugger that most developers never open. The inspector protocol gives you heap snapshots, CPU flame graphs, and step-through debugging without any third-party tools. This article covers the full debugging workflow — from attaching the inspector to diagnosing memory leaks with heap comparisons — using only tools shipped with Node.js and VS Code.

Why Node.js Debugging Is Different

Debugging Node.js is not like debugging client-side JavaScript. You don't have a browser DOM, and your code runs on a server with limited visibility. Traditional console.log debugging works for trivial cases but fails in production where you need to inspect async flows, memory leaks, or race conditions. Node.js provides a built-in inspector protocol that allows external tools to attach and control execution. Understanding this protocol is the foundation for effective debugging. The inspector exposes endpoints for breakpoints, stepping, profiling, and heap snapshots. Tools like Chrome DevTools and VS Code use this protocol under the hood. Without this knowledge, you're flying blind when things break in production.

node --inspect app.js
# Output: Debugger listening on ws://127.0.0.1:9229/...

Setting Up Chrome DevTools for Node.js

Chrome DevTools is the most feature-rich debugger for Node.js. To attach, start your app with --inspect and open chrome://inspect in Chrome. You'll see a list of remote targets. Click 'inspect' to open dedicated DevTools. The Sources tab shows your file system, allows breakpoints, and supports step-through debugging. The Console tab runs in the Node.js context. The Memory and Profiler tabs are invaluable for performance debugging. One common pitfall: if you use --inspect-brk, the app won't start until you attach the debugger. This is useful for debugging startup issues. For production debugging, use --inspect without --inspect-brk to avoid blocking.

node --inspect-brk app.js
# Then open chrome://inspect and click 'inspect'

VS Code Integrated Debugger

VS Code's debugger is the most convenient for daily development. It integrates directly with your editor, allowing you to set breakpoints, inspect variables, and watch expressions without leaving your code. To configure, create a .vscode/launch.json file with a Node.js launch configuration. The key configuration is 'type': 'node' and 'request': 'launch' or 'attach'. Use 'attach' to connect to an already running process (e.g., with --inspect). The 'preLaunchTask' option can run a build step before debugging. VS Code also supports conditional breakpoints, logpoints (console.log without code changes), and hit counts. For monorepos, use 'runtimeArgs' to specify the entry point.

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      "skipFiles": ["<node_internals>/**"],
      "program": "${workspaceFolder}/app.js"
    }
  ]
}

Advanced Breakpoints and Stepping

Breakpoints are the core of debugging. Beyond simple line breakpoints, Node.js supports conditional breakpoints (break only when a condition is true), logpoints (log a message without pausing), and hit count breakpoints (break after N hits). In Chrome DevTools, right-click the line number to set a conditional breakpoint. In VS Code, use the breakpoint context menu. Stepping options: Step Over (F10) executes the current line and moves to the next; Step Into (F11) goes into a function call; Step Out (Shift+F11) finishes the current function and returns. Use 'Continue' (F8) to resume execution until the next breakpoint. For async code, be aware that stepping may jump between async contexts.

function processOrder(order) {
  // Set conditional breakpoint: order.total > 1000
  console.log(`Processing order ${order.id}`);
  // ...
}

const orders = [
  { id: 1, total: 500 },
  { id: 2, total: 1500 },
];
orders.forEach(processOrder);

Debugging Asynchronous Code and Promises

Async code is where Node.js debugging gets tricky. Callbacks, Promises, and async/await create execution contexts that can be hard to trace. The inspector handles async stacks well: when you break inside an async function, the call stack shows the async context chain. In Chrome DevTools, enable 'Async' in the Call Stack panel to see the full async trace. For Promises, use the 'Promise' tab to inspect pending and settled promises. A common bug: unhandled Promise rejections. Node.js will warn about these, but you can break on them by enabling 'Pause on uncaught exceptions' in the debugger. For async/await, stepping works as expected, but be careful with await inside loops — it can cause performance issues.

async function fetchData(url) {
  const response = await fetch(url);
  const data = await response.json();
  return data;
}

async function main() {
  try {
    const data = await fetchData('https://api.example.com/data');
    console.log(data);
  } catch (err) {
    console.error('Failed:', err);
  }
}

main();

Profiling CPU and Memory

Performance issues often require profiling. Node.js's inspector provides CPU and heap profilers. In Chrome DevTools, the Performance tab records CPU samples and shows a flame graph. The Memory tab can take heap snapshots and compare them to find leaks. To start profiling programmatically, use the built-in inspector module. For CPU profiling, use console.profile() and console.profileEnd(). For heap snapshots, use the v8 module's getHeapSnapshot(). In production, use the --prof flag to generate a V8 log file, then process it with --prof-process. Common issues: memory leaks from closures, large buffers not garbage collected, and CPU spikes from synchronous operations.

const inspector = require('inspector');
const fs = require('fs');

function startCPUProfile() {
  const session = new inspector.Session();
  session.connect();
  session.post('Profiler.enable', () => {
    session.post('Profiler.start', () => {
      console.log('CPU profiling started');
    });
  });
  return session;
}

function stopCPUProfile(session) {
  session.post('Profiler.stop', (err, { profile }) => {
    if (!err) {
      fs.writeFileSync('profile.cpuprofile', JSON.stringify(profile));
      console.log('Profile saved');
    }
    session.disconnect();
  });
}

const session = startCPUProfile();
setTimeout(() => stopCPUProfile(session), 5000);

Debugging in Production with --inspect

Debugging in production is risky but sometimes necessary. The safest approach is to use --inspect with a secure WebSocket (wss://) and authentication. Alternatively, use the inspector protocol over a Unix socket to avoid network exposure. Tools like ndb (by Google) provide a secure debugging UI. For containerized apps, expose the inspector port only to a debug sidecar. Never use --inspect without a firewall. A common pattern: start the app with --inspect=0.0.0.0:9229 but bind to localhost in production. Use SSH tunneling to connect: ssh -L 9229:localhost:9229 user@prod-server. Then attach Chrome DevTools to localhost:9229.

# On production server
node --inspect=127.0.0.1:9229 app.js &

# On local machine
ssh -L 9229:localhost:9229 user@prod-server
# Then open chrome://inspect and connect to localhost:9229

Sometimes you can't attach a debugger — especially in serverless or ephemeral environments. In those cases, structured logging and distributed tracing are your friends. Use libraries like pino or winston for JSON logging with log levels. Include request IDs, correlation IDs, and timing information. For tracing, use OpenTelemetry to instrument your code and send traces to a backend like Jaeger or Zipkin. This allows you to see the full lifecycle of a request across services. When debugging, add logpoints (via VS Code or Chrome) that log without code changes. In production, use dynamic log levels: change log level at runtime without restarting the app.

const pino = require('pino');
const logger = pino({
  level: process.env.LOG_LEVEL || 'info',
  formatters: {
    level(label) {
      return { level: label };
    }
  }
});

logger.info({ requestId: 'abc123', user: 'john' }, 'Processing order');
logger.error({ err: new Error('DB timeout') }, 'Order failed');

Common Pitfalls and How to Avoid Them

Even with great tools, developers make mistakes. One common pitfall: debugging minified or transpiled code. Always use source maps. In production, ensure your build process generates source maps and uploads them to your error tracking service. Another pitfall: debugging in a cluster or with child processes. The inspector attaches to the main process only. To debug child processes, start them with --inspect and a different port. Use the 'inspect' option in child_process.fork(). Also, beware of breakpoints in hot code paths — they can cause timeouts in production. Use conditional breakpoints sparingly. Finally, don't rely solely on the debugger; combine it with logging and monitoring.

const { fork } = require('child_process');

const child = fork('worker.js', [], {
  execArgv: ['--inspect=0.0.0.0:9230']
});

child.on('message', (msg) => {
  console.log('From child:', msg);
});

Putting It All Together: A Debugging Workflow

Effective debugging is a workflow. Start with logging: add structured logs at key points. If the issue is reproducible, attach the debugger locally. Use conditional breakpoints to narrow down the problem. For performance issues, profile CPU and memory. For production issues, use SSH tunneling to attach the debugger safely, or rely on logs and tracing. Always have a hypothesis before debugging. Use the scientific method: form a hypothesis, test it with a breakpoint or log, and iterate. Document your findings. After fixing, add a test to prevent regression. Finally, monitor the fix in production with alerts.

// Step 1: Add structured logging
logger.info({ event: 'order_created', orderId }, 'Order created');

// Step 2: If issue persists, attach debugger
// node --inspect-brk app.js

// Step 3: Set conditional breakpoint
// if (order.total > 1000) debugger;

// Step 4: Profile if needed
// console.profile('order-processing');

// Step 5: Fix and add test
// test('order total > 1000', ...);

CLI Debugger: node inspect Commands, Watchers, and REPL

The built-in CLI debugger is often overlooked but invaluable for quick debugging without an IDE. Start with node inspect app.js. This drops you into a debugger prompt where you can use commands like cont (continue), next, step, out, pause, backtrace, and list(n). Use watch('expression') to monitor variables; watchers lists them. The debugger also provides a REPL: type repl to evaluate expressions in the current scope. For example, watch('req.url') and then repl to inspect req.headers. Exit REPL with Ctrl+D. This is perfect for serverless or CI environments where Chrome DevTools isn't available. The CLI debugger respects the same --inspect protocol, so you can attach later. Pro tip: use node inspect --inspect-brk app.js to break on first line.

$ node inspect app.js
< Debugger listening on ws://127.0.0.1:9229/...
< For help, see: https://nodejs.org/en/docs/inspector
< Debugger attached.
break in app.js:1
> 1 const http = require('http');
  2 const hostname = '127.0.0.1';
  3 const port = 3000;
debug> watch('hostname')
debug> watchers
  0: hostname = "127.0.0.1"
debug> cont
< server running at http://127.0.0.1:3000/
... (hit Ctrl+C to stop)

launch.json Advanced Configuration for Node.js

VS Code's launch.json is more powerful than most realize. Beyond basic type: node, you can configure runtimeArgs for --inspect-brk, env for environment variables, cwd for working directory, outputCapture to capture stdout/stderr, and skipFiles to skip node_modules or internal Node.js files. Use preLaunchTask to run a build step before debugging. For TypeScript, set preLaunchTask: "tsc: build - tsconfig.json" and outFiles to map compiled JS. The resolveSourceMapLocations option controls which source maps are resolved. Example: "resolveSourceMapLocations": ["${workspaceFolder}/", "!/node_modules/**"]. You can also use localRoot and remoteRoot for remote debugging. Pro tip: use console: "integratedTerminal" to see console output in the terminal instead of the debug console.

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      "skipFiles": ["<node_internals>/**"],
      "program": "${workspaceFolder}/dist/index.js",
      "outFiles": ["${workspaceFolder}/dist/**/*.js"],
      "preLaunchTask": "tsc: build - tsconfig.json",
      "env": { "NODE_ENV": "development" },
      "console": "integratedTerminal",
      "resolveSourceMapLocations": [
        "${workspaceFolder}/**",
        "!**/node_modules/**"
      ]
    }
  ]
}

Multi-Target Debugging: Debug Multiple Processes Simultaneously

Modern Node.js apps often run multiple processes (e.g., microservices, worker threads, or a frontend + backend). VS Code supports multi-target debugging via a compound configuration. Define each process as a separate launch configuration, then create a compound that runs them together. Example: debug an Express API and a WebSocket server concurrently. Use "stopAll": true to stop all when one stops. For worker threads, use "autoAttachChildProcesses": true in the parent config. This attaches the debugger to any child processes spawned. Alternatively, use "attach" configurations for processes already running with --inspect. Pro tip: set "restart": true to automatically reattach if the process restarts (useful with nodemon).

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "API Server",
      "program": "${workspaceFolder}/api/server.js",
      "port": 9229
    },
    {
      "type": "node",
      "request": "launch",
      "name": "WebSocket Server",
      "program": "${workspaceFolder}/ws/server.js",
      "port": 9230
    }
  ],
  "compounds": [
    {
      "name": "Full Stack",
      "configurations": ["API Server", "WebSocket Server"],
      "stopAll": true
    }
  ]
}

Source Maps for TypeScript: Debug .ts Files Directly

Debugging TypeScript requires source maps to map compiled JavaScript back to TypeScript. Enable "sourceMap": true in tsconfig.json. In VS Code, set outFiles to the output directory and ensure resolveSourceMapLocations includes your source. The debugger will then let you set breakpoints in .ts files. For complex setups (e.g., path mapping, project references), use sourceMapPathOverrides to remap paths. Example: "sourceMapPathOverrides": { "webpack:///./src/": "${workspaceFolder}/src/" } for webpack. Pro tip: always test source maps by setting a breakpoint in a .ts file and verifying it hits. If not, check that the .js file has a //# sourceMappingURL comment.

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "sourceMap": true,
    "strict": true
  },
  "include": ["src/**/*"]
}

Remote Debugging Over SSH: Debug Node.js on a Remote Server

When your app runs on a remote server (e.g., staging), you can debug it locally using SSH port forwarding. Start the Node.js process with --inspect=0.0.0.0:9229 (bind to all interfaces) but secure it with a firewall. On your local machine, run ssh -L 9229:localhost:9229 user@remote-server. Then in VS Code, create an attach configuration with "port": 9229. Alternatively, use --inspect-publish-uid=http to restrict to specific IPs. For production, never expose the inspector port publicly; use SSH tunneling or a VPN. Pro tip: use --inspect-brk to pause on first line, then attach. This is great for debugging startup issues.

# On remote server
$ node --inspect=0.0.0.0:9229 app.js

# On local machine
$ ssh -L 9229:localhost:9229 user@remote-server

# In VS Code launch.json
{
  "type": "node",
  "request": "attach",
  "name": "Attach to Remote",
  "port": 9229,
  "localRoot": "${workspaceFolder}",
  "remoteRoot": "/path/to/app"
}

Heap Snapshot Generation and Memory Leak Debugging

Memory leaks in Node.js can be elusive. Generate heap snapshots using the v8 module: require('v8').getHeapSnapshot().pipe(fs.createWriteStream('heap.heapsnapshot')). Load the snapshot in Chrome DevTools (Memory tab) to compare objects. For automated leak detection, use heapdump package: heapdump.writeSnapshot('/tmp/heap-1.heapsnapshot'). Compare two snapshots to see retained objects. Clinic.js (specifically clinic heapprofiler) provides a flamegraph-like view. Pro tip: trigger snapshots on demand via a signal: process.on('SIGUSR2', () => heapdump.writeSnapshot()). For long-running processes, use --max-old-space-size to set memory limits and --trace-gc to log GC events.

const v8 = require('v8');
const fs = require('fs');

// Generate heap snapshot
const snapshotStream = v8.getHeapSnapshot();
const fileStream = fs.createWriteStream('/tmp/heap.heapsnapshot');
snapshotStream.pipe(fileStream);

// Or using heapdump package
const heapdump = require('heapdump');
heapdump.writeSnapshot('/tmp/heap-' + Date.now() + '.heapsnapshot', (err, filename) => {
  if (err) console.error(err);
  else console.log('Snapshot written to', filename);
});