Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท CLI Flags

Node.js --inspect and --inspect-brk flags

Reference for node --inspect, --inspect-brk and --inspect-wait: start the V8 inspector, attach Chrome DevTools or VS Code, and avoid exposing the port.

--inspect starts the V8 inspector inside the Node.js process. The inspector is a WebSocket server that speaks the Chrome DevTools Protocol, so Chrome DevTools, VS Code, WebStorm and other debuggers can attach, set breakpoints, step through code, profile and take heap snapshots.

The three common forms differ only in when your code starts: --inspect runs immediately, --inspect-brk pauses on the first line until a debugger attaches, and --inspect-wait waits for a debugger without stopping on the first line.

NODE
// shell: node --inspect-brk app.js

Try it

Node.js What the inspector announces

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Talking to the inspector from inside the program

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
// shell
node --inspect[=[host:]port] <script>
node --inspect-brk[=[host:]port] <script>
node --inspect-wait[=[host:]port] <script>
node inspect <script>
Name Description
--inspect Opens the inspector on 127.0.0.1:9229 by default and runs the script right away.
--inspect-brk Opens the inspector and pauses before the first line of user code.
--inspect-wait Opens the inspector and waits for a debugger to attach, then continues without an initial pause.
[host:]port Optional address. Port 0 picks a free port; the default is 9229.
node inspect A separate, text-based command-line debugger (a command, not a flag).

Returns: nothing. The WebSocket address is printed to stderr as Debugger listening on ws://..., and http://host:port/json lists the debug targets.

Edge cases: if the port is already taken, Node prints an error and the program keeps running without a debugger (with plain --inspect).

Usage notes

  • Attach DevTools by opening chrome://inspect in a Chromium browser, or edge://inspect in Edge, and choosing the target. VS Code attaches through an "attach" launch configuration or its JavaScript Debug Terminal.
  • Use --inspect-brk for scripts that finish quickly. Without it the program may end before you can attach.
  • Security: anyone who can reach the port can run arbitrary code as your user. Keep the default 127.0.0.1 binding. Never bind to 0.0.0.0 on a shared or public network; tunnel with SSH instead.
  • Containers: a debugger outside the container cannot reach 127.0.0.1 inside it. Publish the port and bind to a reachable address only on a trusted network.
  • Signal activation: on Linux and macOS, sending SIGUSR1 to a running process starts the inspector on the default port, which helps with an already running server.
  • Child processes started with fork() inherit --inspect and try a port one higher each time; set execArgv yourself to avoid clashes.
  • Performance: an attached debugger and breakpoints slow the program. Do not leave the inspector on in production.
  • In-process access: the node:inspector module (Session, url(), open(), close(), waitForDebugger()) lets code use the same protocol without a UI; see the second example.