How to Remote Debug Node.js

Finding and fixing bugs is not always easy, especially if someone else wrote the code!

I know that engineers in general have NIH syndrome, but I am one that doesn’t share that view. Technology is an enabler, meaning it’s not an end goal, it is there to provide a service (or at least that is how it is most of the time).

As such, we must sometimes make fixes to our code, or to other people’s code, and that requires debugging. I’ve seen many people use console.log/logger/printf – heck, sometimes they even suggested that I do it that way. But as much as I enjoy waterboarding myself, I’d much rather use a debugger whenever I can. Debugging a node.js project isn’t complex, it just requires a little bit of setup, after which you can debug a local app or even a remote production/staging/test environment.

The first step is to run node.js with the special debug flag and the optional port:

node --debug <-- run node with debugging on port 5858

node --debug=4455 <-- runs node with debugging on port 4455 (you change the port)

node --debug-brk <-- run node with debugging and will break on first statement

If you’re using gulp/nodemon etc, be sure to include those flags in a separate task and/or pass the relevant params to your node app.

// Nodemon task
gulp.task('remote_debug', function () {
return plugins.nodemon({
script: 'server.js',
nodeArgs: ['--harmony', '--debug=5577'],
ext: 'js,html',

Then you can launch your app, or do it via the task, and your node.js app is running and allowing any debugger to connect to it.

You can use any node.js you choose. I personally use phpstorm/webstorm. While it’s not a perfect product and has some issues, I’ve had very successful debugging sessions with it, and I’ll try and outline how to set that up.

First install webstorm/phpstorm. Both IDEs are great and very similar, except Phpstorm also allows you to edit and work on PHP files, whereas Webstorm mainly concentrates on JS files and web files.

After the install, launch the app and go into the plugin:

Go to File->Settings and in that screen click on the plugins menu item.


The click on the “Install JetBrains plugin…” button and in the new window either scroll down or search in the top search box for NodeJS plugin.

Once the install is finished, you should have NodeJS installed and you can go ahead and open your projects directory in the IDE. (File->Open Directory, obvious I know, but still… 😉 )

In the last step we need to configure the remote config for our node project.

Click on Run -> Edit Configurations… Menu.

And Click on the + button and select Node.js Remote Debug.


Then in the main window just setup the server address and port (this can be used to debug a remote machine or a local machine)
And you’re all setup to start debugging your server!


Then click ok, select the configuration from the top right-hand side menu and click on the little bug icon button:


At this stage you’re up and running. If you look at the bottom debug tab you should see you’re connected and then you can put a breakpoint anywhere in your code and solve any bug you come across like a hero (at least in theory! 🙂 ).

***** Important note *****

While Phpstorm/Webstorm is wonderful, I’ve had some issues with debugging performance. This issue relates to some settings in the software so to ensure you do not get frustrated waiting for the first breakpoint to hit, I would suggest you configure Phpstorm/Webstorm as follows:

1) Click on help -> “Find Action” (ctrl + shift + a)
2) In the searchbox type: Registry.
3) Then start typing (or scroll down) and find
js.debugger.v8.use.any.breakpoint – turn off

Happy Hunting!