Node Inspector

About Node Inspector

Node Inspector is a tool that allows you to debug server side Node.js code in the same way that you would debug front end JavaScript. It utilizes the same interface as Chrome Developer Tools, allowing you to pause execution on breakpoints or at the debugger keyword, providing access to the state of variables, the call stack, and a JavaScript console at any specified point in the program.

Why Node Inspector?

The Node Inspector — and the Chrome Developer Tools in general — provides a much more powerful and effective debugging mechanism than simply using console log outputs, as it permits the developer to inspect, and even modify, the state of the whole program at each step of it’s execution, rather than simply seeing a log output for the state of a particular variable at a single point in time.

Getting Started

The Node Inspector can be installed globally via npm. The documentation is found here: https://github.com/node-inspector/node-inspector. If you haven’t already installed Node Inspector, run the following command:

> npm install -g node-inspector

Once installed, you will have access to the following command:

> node-debug <your node.js file>

The purpose of this article is to expose some common pitfalls that new users of the Node Inspector are vulnerable to. Before running this command on your own, I recommend that you continue reading and execute it alongside the following usage instructions.

Important Gotcha’s

Node Inspector uses 2 ports

8080: The “web port,” which displays the debugger interface.

5858: The “debug port,” which runs the node engine in the background

Key Takeaway: Don’t use either of these ports to run your server. Probably the most common reason for frustration with Node Inspector is that developers are trying to run their server on port 8080, which is being used by Node Inspector.

Watch out for Pause on Caught Exceptions

If you’re running older versions of Node (older than v0.11.3), you must not use Pause on Caught Exceptions. If you do, the inspector will throw errors that don’t really exist. This is listed in the known issues (https://github.com/node-inspector/node-inspector#known-issues), which I recommend reading through. Best practice is just to upgrade to the latest version of Node. If you’re unsure of which version of Node you have, run the following command:

> node -v

Sequence

While using the Node Inspector, it’s easy to make incorrect assumptions about how it will behave when you refresh the page, make changes to your code, restart your server, etc. Avoid frustration by following the specific sequences that are outlined below.

Usage

Starting Node Inspector

Run the command: node-debug <your-server-file>

Get Brian Loughnane’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

What does this do?

1. Starts your server and the Node Inspector
2. Opens a browser tab with the debugger interface
3. Pauses execution on the top line of your server-file

Inspecting Your Server File

After running the command: node-debug <your-server-file>, you can step through the code on your server file line by line, set breakpoints, or resume execution to pause on pre-set debugger statements.

Key takeaway: The server file is only run once when starting up your server (and thus when starting the inspector). Therefore, once execution of the server file is complete, you must re-start the Node Inspector to debug it again.

Restarting Node Inspector

1. Close the debugger interface browser tab
2. In terminal, ctrl+c to kill the node-debug process
3. Re-run the command: node-debug <your-server-file>

Key takeaway: While performing these steps repeatedly is cumbersome, it is a necessary sequence for the Node Inspector to work properly, so follow these steps precisely each time you need to restart the Node Inspector.

Debugging Request Handlers

1. Run command: > node-debug <your-server-file>
2. In the debugger interface, resume execution through to the end of your server file, or at least past the request handler function*
3. Set breakpoints within the request handler function as needed
4. Make a request to your server

*you may not be able to set breakpoints within your request handler until execution has move past it — this is just a quirk of Node Inspector

While the server file is only run once, request handler functions are executed each and every time a request is made to the route that the request handler is fielding. Therefore, you do not need to restart the inspector to access breakpoints set in the request handler functions. Simply continue making requests in order to access the breakpoints.

Making Changes to Code

Key takeaway: Any time you make changes to any server side code, restart the Node Inspector. Follow the steps above to do so.

Summary

The Node Inspector is a powerful tool for debugging your server side Node.js code, and is ultimately worth figuring out if you are going to work with Node. While it is quirky, you may find that in following the above outlined sequences, it becomes more predictable. If you are getting strange errors or something doesn’t look right, simply restarting the Node Inspector will solve the issue much of the time.