node --inspect: open the debugger for Chrome DevTools and VS Code
- tool
- Node.js
- command
- node
- flag
- --inspect[=[host:]port]
- default
- off; when given without a value, 127.0.0.1:9229
node --inspect app.js starts the V8 inspector: Node.js listens on 127.0.0.1:9229 for a debugger client, prints a ws:// URL and then runs the script normally. Chrome DevTools (chrome://inspect), VS Code, WebStorm and other clients attach to that port and can set breakpoints, step through code and inspect memory. Use --inspect-brk when you need the process to stop on the first line and wait for you.
What it prints
The inspector announces the address and a random session id (replaced by <uuid> here). A second process cannot open the same port:
node --inspect=127.0.0.1:5310 -e 'setTimeout(() => {}, 300)' 2>&1 | sed -E 's#/[0-9a-f-]{36}#/<uuid>#'
echo "--- the port is already taken"
node --inspect=127.0.0.1:5311 -e 'setTimeout(() => {}, 2500)' 2>/dev/null &
sleep 1
node --inspect=127.0.0.1:5311 -e 'console.log("script still runs")' 2>&1 | sed -E 's#/[0-9a-f-]{36}#/<uuid>#'
waitOutput
Debugger listening on ws://127.0.0.1:5310/<uuid> For help, see: https://nodejs.org/learn/getting-started/debugging --- the port is already taken Starting inspector on 127.0.0.1:5311 failed: address already in use script still runs
The messages go to stderr, not stdout, so they do not mix with the program's own output. When the port is busy, Node.js reports the failure and still runs the script, only without a debugger.
The variants
| Flag | What it does |
|---|---|
| --inspect | Listen on 127.0.0.1:9229 and run the script at once |
| --inspect=9230 | Same, on another port (useful when several processes are debugged) |
| --inspect=0 | Pick a free port at random; read it from the printed URL |
| --inspect=0.0.0.0:9229 | Listen on every interface (containers, remote machines); a security risk |
| --inspect-brk | Listen and pause before the first line of user code until a client continues |
| --inspect-wait | Listen and wait for a client to attach, then run without pausing (Node.js 22.2+) |
| --inspect-port=PORT | Set the port used when the inspector is activated later (SIGUSR1) |
Attaching a client
- Chrome or Edge: open
chrome://inspect(oredge://inspect); local targets on port 9229 appear under "Remote Target". Add other ports with "Configure". - VS Code: use the "Attach" configuration of the JavaScript debugger, or simply start the script from a JavaScript Debug Terminal, which sets the flag for you.
- From code:
require("node:inspector").url()returns the WebSocket URL, orundefinedwhen the inspector is not active.
Pitfalls
Starting inspector on 127.0.0.1:9229 failed: address already in usemeans another debugged process (often a previous run, or a child process that inheritedNODE_OPTIONS=--inspect) already holds the port. Use--inspect=0or a different port. The same "address in use" idea applies to your HTTP server: see EADDRINUSE.- With
--inspect, short scripts finish before you can attach. Use--inspect-brkor--inspect-wait. - The flag must come before the script name:
node app.js --inspectpasses--inspectto your program inprocess.argvinstead. - A running process without the flag can be switched on later on Linux and macOS by sending it
SIGUSR1; it then listens on the default port.
FAQ
What is the difference between --inspect and --inspect-brk?
--inspect starts the debugger and runs the script immediately, so breakpoints set later only catch code that has not run yet. --inspect-brk pauses before the first line of user code and waits until a debugger client continues, which is what you need to debug startup code.
How do I debug a Node.js app inside Docker with --inspect?
Bind to all interfaces with --inspect=0.0.0.0:9229 and publish the port (-p 9229:9229). Only do this on a trusted network: anyone who reaches the port can run arbitrary code in the process.
Can I pass --inspect through npm scripts?
Yes. Put it in the script (node --inspect server.js) or set NODE_OPTIONS=--inspect, which every node process started by the script will read. With NODE_OPTIONS, child processes also try to open the same port and fail with address already in use.