Debugging Node.js Applications

Master debugging techniques using the Inspector protocol, Chrome DevTools, and command-line tools

Overview

Node.js provides powerful debugging capabilities through the V8 Inspector protocol, enabling you to debug applications using Chrome DevTools, VS Code, and other debugging clients.

Command-Line Debugger

Node.js includes a built-in command-line debugging utility for simple stepping and inspection.

Starting the Debugger

Start Node.js with the inspect argument:

node inspect myscript.js

Output:

< Debugger listening on ws://127.0.0.1:9229/621111f9-ffcb-4e82-b718-48a145fa5db8
< For help, see: https://nodejs.org/en/docs/inspector
connecting to 127.0.0.1:9229 ... ok
< Debugger attached.

Break on start in myscript.js:2
  1 // myscript.js
> 2 global.x = 5;
  3 setTimeout(() => {
  4   debugger;
debug>

The debugger automatically breaks on the first executable line.

Resume on Start

To run until the first debugger statement instead of breaking immediately:

NODE_INSPECT_RESUME_ON_START=1 node inspect myscript.js

Debugger Commands

Stepping Commands

cont, c · command

Continue execution

next, n · command

Step to next line

step, s · command

Step into function

out, o · command

Step out of function

pause · command

Pause running code

Breakpoint Commands

# Set breakpoint on current line
setBreakpoint()
sb()

# Set breakpoint on specific line
setBreakpoint(line)
sb(line)

# Set breakpoint in function
setBreakpoint('fn()')

# Set breakpoint in file
setBreakpoint('script.js', 1)

# Conditional breakpoint
setBreakpoint('script.js', 1, 'num < 4')

# Clear breakpoint
clearBreakpoint('script.js', 1)
cb('script.js', 1)

Information Commands

backtrace, bt · command

Print backtrace of current execution frame

list(5) · command

List source code with 5 line context

watch(expr) · command

Add expression to watch list

watchers · command

List all watchers and their values

repl · command

Open debugger REPL for evaluation

exec expr · command

Execute expression and print value

Using Watchers

Watch expression values at each breakpoint:

// Add a watcher
watch('myVariable')
watch('obj.property')

// List all watchers
watchers

// Remove a watcher
unwatch('myVariable')

REPL Mode

Evaluate code in the debugging context:

debug> repl
Press Ctrl+C to leave debug repl
> x
5
> 2 + 2
4
> myFunction()
'result'

Press Ctrl+C to exit REPL mode.

V8 Inspector Protocol

The V8 Inspector enables powerful debugging with Chrome DevTools and other clients.

Inspector Flags

--inspect

Start with inspector enabled. Code runs immediately.

node --inspect index.js

Output:

Debugger listening on ws://127.0.0.1:9229/dc9010dd-f8b8-4ac5-a510-c1a114ec7d29
For help, see: https://nodejs.org/en/docs/inspector

--inspect-wait

Wait for debugger to attach before executing code.

node --inspect-wait index.js

--inspect-brk

Break on the first line as soon as debugger attaches.

node --inspect-brk index.js

Custom Port

Specify a custom debugging port:

node --inspect=9222 index.js
node --inspect=0.0.0.0:9222 index.js  # Listen on all interfaces

Binding the inspector to a public IP:port combination is insecure. Ensure proper firewall rules are in place.

Chrome DevTools Integration

Connecting Chrome DevTools

1. Start Node.js with inspector

   node --inspect-brk app.js
   
2. Open Chrome

   Navigate to chrome://inspect in Google Chrome

3. Configure target discovery

   Click “Configure” and add localhost:9229 to the target list

4. Inspect

   Click “inspect” under your Node.js process

DevTools Features

• Sources Panel: Set breakpoints, step through code
• Console: Evaluate expressions in the current context
• Profiler: Record CPU profiles
• Memory: Take heap snapshots
• Network: Inspect network requests (with --experimental-network-inspection)

VS Code Debugging

Launch Configuration

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      "skipFiles": ["<node_internals>/**"],
      "program": "${workspaceFolder}/app.js"
    },
    {
      "type": "node",
      "request": "attach",
      "name": "Attach to Process",
      "port": 9229,
      "restart": true
    }
  ]
}

Debug Current File

{
  "type": "node",
  "request": "launch",
  "name": "Debug Current File",
  "program": "${file}",
  "skipFiles": ["<node_internals>/**"]
}

Debug with Arguments

{
  "type": "node",
  "request": "launch",
  "name": "Launch with Args",
  "program": "${workspaceFolder}/app.js",
  "args": ["--config", "production.json"],
  "env": {
    "NODE_ENV": "development"
  }
}

Using the Inspector API

Programmatically control the inspector from your code.

Opening the Inspector

const inspector = require('node:inspector');

// Open inspector on default port
inspector.open();

// Open on specific port
inspector.open(9229, 'localhost');

// Wait for debugger to attach
inspector.open(9229, 'localhost', true);

CPU Profiling

import { Session } from 'node:inspector/promises';
import fs from 'node:fs';

const session = new Session();
session.connect();

await session.post('Profiler.enable');
await session.post('Profiler.start');

// Run code to profile
performExpensiveOperation();

const { profile } = await session.post('Profiler.stop');
fs.writeFileSync('./profile.cpuprofile', JSON.stringify(profile));

Heap Snapshots

import { Session } from 'node:inspector/promises';
import fs from 'node:fs';

const session = new Session();
const fd = fs.openSync('profile.heapsnapshot', 'w');

session.connect();

session.on('HeapProfiler.addHeapSnapshotChunk', (m) => {
  fs.writeSync(fd, m.params.chunk);
});

await session.post('HeapProfiler.takeHeapSnapshot', null);
session.disconnect();
fs.closeSync(fd);

Taking Heap Snapshots from Debugger

From the command-line debugger:

debug> takeHeapSnapshot('snapshot.heapsnapshot')

Debugging Best Practices

Use debugger Statement

Add debugger; statements in your code to create breakpoints:

function processData(data) {
  debugger; // Execution will pause here
  return data.map(item => item * 2);
}

Enable Source Maps

For TypeScript or transpiled code, enable source maps:

node --enable-source-maps dist/app.js

Skip Node Internals

Focus on your code by skipping Node.js internals in VS Code:

{
  "skipFiles": ["<node_internals>/**", "node_modules/**"]
}

Use Conditional Breakpoints

Break only when specific conditions are met:

setBreakpoint('app.js', 42, 'user.id === 123')

Remote Debugging

SSH Tunneling

Debug a remote Node.js application securely:

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

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

Then connect Chrome DevTools to localhost:9229.

Troubleshooting

Debugger Won't Connect

• Verify the port is not blocked by firewall
• Check if another process is using port 9229
• Ensure you’re connecting to the correct IP/port

Source Maps Not Working

• Enable source maps: --enable-source-maps
• Ensure source map files (.map) are present
• Check sourceRoot in tsconfig.json

Breakpoints Not Hitting

• Verify code is actually being executed
• Check if using —inspect-brk for early breakpoints
• Ensure file path matches exactly

Next Steps

Performance

Profile and optimize your code

Testing

Write and run tests