Node Inspector

Overview

Since version 6.3, Node.js provides a buit-in DevTools-based debugger which mostly deprecates Node Inspector, see e.g. this blog post to get started. The built-in debugger is developed directly by the V8/Chromium team and provides certain advanced features (e.g. long/async stack traces) that are too difficult to implement in Node Inspector.

Troubleshooting

My script runs too fast to attach the debugger.

The debugged process must be started with --debug-brk, this way the script is paused on the first line.

Note: node-debug adds this option for you by default.

I got the UI in a weird state.

When in doubt, refresh the page in browser

Can I debug remotely?

Yes. Node Inspector must be running on the same machine, but your browser can be anywhere.
Just make sure port 8080 is accessible.

And if Node Inspector is not running on your remote machine, you can also debug it as long as your local machine can connect it.
In this way, you must launch Node Inspector with --no-inject which means some features are not supported such as profiling and consoling output inspection.

option 2

How do I specify files to hide?

Create a JSON-encoded array. You must escape quote characters when using a command-line option.

$ node-inspector --hidden='["node_modules/framework"]'

Note that the array items are interpreted as regular expressions.

UI doesn't load or doesn't work and refresh didn't help

Make sure that you have adblock disabled as well as any other content blocking scripts and plugins.

How can I (selectively) delete debug session metadata?

You may want to delete debug session metadata if for example Node Inspector gets in a bad state with some
watch variables that were function calls (possibly into some special c-bindings). In such cases, even restarting
the application/debug session may not fix the problem.

Node Inspector stores debug session metadata in the HTML5 local storage.
You can inspect the contents of local storage and remove any items as
needed. In Google Chrome, you can execute any of the following in the JavaScript console:

// Remove all

window.localStorage.clear()

// Or, to list keys so you can selectively remove them with removeItem()

window.localStorage

// Remove all the watch expressions

window.localStorage.removeItem('watchExpressions')

// Remove all the breakpoints

window.localStorage.removeItem('breakpoints')

When you are done cleaning up, hit refresh in the browser.

Node Inspector takes a long time to start up.

Try setting --no-preload to true. This option disables searching disk for *.js at startup.
Code will still be loaded into Node Inspector at runtime, as modules are required.

How do I debug Mocha unit-tests?

You have to start _mocha as the debugged process and make sure
the execution pauses on the first line. This way you have enough
time to set your breakpoints before the tests are run.

$ node-debug _mocha

How do I debug Gulp tasks?

If you are running on a Unix system you can simply run the following command.
The $(which ..) statement gets replaced with the full path to the gulp-cli.

$ node-debug $(which gulp) task

If you are running on Windows, you have to get the full path of gulp.js
to make an equivalent command:

> node-debug %appdata%\npm\node_modules\gulp\bin\gulp.js task

You can omit the task part to run the default task.

Advanced Use

While running node-debug is a convenient way to start your debugging
session, there may come time when you need to tweak the default setup.

There are three steps needed to get you up and debugging:

1. Start the Node Inspector server

$ node-inspector

You can leave the server running in background, it's possible to debug
multiple processes using the same server instance.

2. Enable debug mode in your Node process

You can either start Node with a debug flag like:

$ node --debug your/node/program.js

or, to pause your script on the first line:

$ node --debug-brk your/short/node/script.js

Or you can enable debugging on a node that is already running by sending
it a signal:

Get the PID of the node process using your favorite method.
pgrep or ps -ef are good

$ pgrep -l node

2345 node your/node/server.js

Send it the USR1 signal

$ kill -s USR1 2345

Windows

Windows does not support UNIX signals. To enable debugging, you can use
an undocumented API function process._debugProcess(pid):