skip to content

How do you attach a debugger to a Node.js process, and how do `--inspect`, `--inspect-wait` and `--inspect-brk` differ?

level: juniorimportance: should knowfreq 55%

answer

  1. a protocol endpoint, not a package
  2. loopback address, port 9229
  3. run now, wait, or pause
  4. first line versus first client

basics

~20 s

Start Node with --inspect to open a Chrome DevTools Protocol endpoint, by default on 127.0.0.1:9229, then attach DevTools, an IDE or node inspect. --inspect runs immediately, --inspect-wait waits for a client, --inspect-brk also pauses on line one.

solid answer

~40 s

Node has the V8 inspector built in: `node --inspect app.js` opens a WebSocket endpoint that speaks the Chrome DevTools Protocol, on `127.0.0.1:9229` unless you pass `--inspect=host:port` (port `0` picks a free one). Chrome DevTools, an IDE, or the bundled `node inspect` client attach to it for breakpoints, stepping and profiling. The three flags differ only in what happens before a client connects: `--inspect` starts running your code straight away, so startup code is already gone by the time you attach; `--inspect-wait` holds execution until a debugger attaches; `--inspect-brk` also stops on the first line of your script once one does. Keep the default loopback host: binding to `0.0.0.0` lets anyone who reaches the port run code in the process.

code

bash · 5 lines
bash
node --inspect server.js            # runs now; attach any time
node --inspect-wait server.js       # waits for a debugger before running
node --inspect-brk server.js        # waits, then pauses on the first line
node --inspect=0 worker.js          # random free port, printed to stderr
node inspect -p 4123                # built-in CLI client, attach by pid

go deeper

for a junior

Know the flag, the default 127.0.0.1:9229 address, and that Chrome DevTools or your IDE attaches to it. Be able to say which flag lets you debug start-up code.

for a middle

Explain the run, wait and break-on-first-line difference, how port 0 and --inspect-port work, and how a client discovers the target through the printed WebSocket URL.

for a senior

Show you know the security warning: the inspector is unauthenticated code execution, so it stays on loopback and is reached through a tunnel, never a public interface.

for a principal

Have a view on how a team debugs services consistently: launch configurations checked in, inspector never exposed beyond loopback, and debugging done on a reproduced copy rather than a live instance.

## What the inspector is Node.js ships a debugger server inside the runtime. It is the **V8 inspector**, the same engine-level debugging interface Chrome uses, and Node exposes it over a WebSocket that speaks the **Chrome DevTools Protocol** (CDP). Nothing has to be installed in the application: you start the process with a flag, a client connects, and from then on the client can set breakpoints, step through code, evaluate expressions, read variables and record CPU or heap profiles. When the inspector starts, Node prints where it is listening to stderr: ```console $ node --inspect index.js Debugger listening on ws://127.0.0.1:9229/dc9010dd-f8b8-4ac5-a510-c1a114ec7d29 For help, see: https://nodejs.org/learn/getting-started/debugging ``` The UUID at the end of the URL is generated for each session. By default the same URL is also listed over HTTP at `http://host:port/json/list`, which is how DevTools and IDEs discover a target (`--inspect-publish-uid` controls those two channels). ## The three start-up flags All three activate the inspector on `host:port`, defaulting to `127.0.0.1:9229`. They differ in what your code does before a debugger client connects. | Flag | Code before a client attaches | After a client attaches | |---|---|---| | `--inspect` | runs immediately | keeps running until it hits a breakpoint | | `--inspect-wait` | does not start | starts running | | `--inspect-brk` | does not start | pauses on the first line of the script | - Use **`--inspect`** for a long-running server where the bug happens on a later request: you attach whenever you like. - Use **`--inspect-wait`** when the bug is in start-up code (configuration loading, a module that throws on import) but you only need your own breakpoints to fire. - Use **`--inspect-brk`** when you want to step from the very first statement. `--inspect-wait` is the newest of the three; the `cli.md` history records it as added in v22.2.0 and v20.15.0, so every supported release line has it. ## Choosing the host and port The flags take an optional `[host:]port`: `--inspect=9230` changes the port, `--inspect=0` asks for a random free port (useful when several processes start at once), and `--inspect=127.0.0.1:9230` sets both. `--inspect-port` sets the address to use if the inspector is activated later rather than at start-up. The host deserves care. Node's documentation carries an explicit warning: **binding the inspector to a public IP, including `0.0.0.0`, with an open port is insecure**, because any host that can reach it can connect and run arbitrary code in the process. The inspector has no login. Keep it on loopback and reach a remote machine through an SSH tunnel or a port-forward. ## Attaching a client 1. **Chrome DevTools** (or another Chromium-based browser) discovers local targets through the `/json/list` endpoint and opens a dedicated Node debugging window. 2. **An IDE** such as VS Code or a JetBrains IDE either launches Node with the flag itself or attaches to a given port. 3. **`node inspect`** is the command-line client bundled with Node: `node inspect app.js` starts the script under the inspector and breaks on the first executable line, `node inspect host:port` attaches to a running inspector, and `node inspect -p <pid>` attaches to a running process by its process id. It is basic stepping and inspection, not a full IDE debugger. Code can also ask where its own inspector is: `inspector.url()` from `node:inspector` returns the `ws://` URL, or `undefined` when no inspector is active. ## Turning it on from inside the process The flags are not the only switch. `inspector.open([port[, host[, wait]]])` activates the inspector in a process that is already running, exactly as if it had been started with `--inspect=host:port`; with `wait` set to `true` it blocks until a client connects. Since v20.6.0 it returns a `Disposable` that closes the inspector again. `inspector.waitForDebugger()` blocks until an attached client tells the runtime to continue, and `inspector.close()` shuts the inspector down and terminates any active connections. These are handy for a development-only switch, and the same host warning applies to them. ## Mistakes that waste a debugging session - Starting with `--inspect` and wondering why a breakpoint in start-up code never fired: that code ran before you attached. - Using `--inspect=0.0.0.0` on a shared or cloud host "just for a minute". - Two processes both asking for port 9229: the second cannot bind its inspector, so give each its own port or use `0`. - Forgetting that a paused breakpoint freezes the whole event loop, so every other request the process is serving waits too.

  • Why is `--inspect=0.0.0.0:9229` dangerous on a server?
    The inspector has no authentication. Anyone who can reach that port can connect a client, evaluate arbitrary JavaScript inside the process and read its memory, which Node's own documentation calls a remote code execution risk. Keep the default `127.0.0.1` and reach remote machines through an SSH tunnel or a port-forward, or make sure a firewall blocks the port.
  • How can a running script find out the URL of its own inspector?
    Call `inspector.url()` from `node:inspector`. It returns the `ws://host:port/<uuid>` address of the active inspector, or `undefined` when the process was started without one. The same URL is printed to stderr at start-up and, by default, listed at `http://host:port/json/list`.

  • Saying --inspect pauses the program until a debugger attaches
  • Believing the inspector listens on all network interfaces by default
  • Thinking a debugger package must be installed into the app first
  • Treating --inspect-wait and --inspect-brk as the same flag
  • Exposing --inspect=0.0.0.0 on a reachable host without a firewall