Node.js remote debug in WebStorm

Node.js remote debug is the perfect option for the cases, when you project is run inside the Vagrant box.
Luckly, both node.js and WebStorm have all the needed options, to make the debug still possible and convenient.

Below it’s described how to configure the Node.js Remote Debug in WebStorm.


My WebStorm version is 11, node.js version is 4.2.2.

Let’s assume, that my Vagrant box configured to be in private network with my machine, and it exposes all the ports to the IP 192.168.33.10.

node.js remote debug with WebStorm example

  1. Our node.js app is a simple hapijs server.

  2. Being inside the Vagrant server we should run the app with the next command:

    In the console we will see the next:

    node.js remote debug with WebStorm
    As well, the app works through the browser:
    node.js remote debug with WebStorm

  3. Next, let’s configure the WebStorm part. We should create new run/debug configuration for our project.
    In case of remote debug, it’s not possible to run the application, it’s possible only to debug.
    node.js remote debug with WebStorm
    Click “Apply” and that’s it.
  4. Now, we are able to set the breakpoint and connect our debugger.
    node.js remote debug with WebStorm
  5. Now, let’s try to open the next url in the browser: http://192.168.33.10:3000/?param=123 .
    If everything is setup correctly, you will be brought back to the WebStorm right to the middle of the debug session:node.js remote debug with WebStorm
  6. Cool, you don’t need to spoil your private PC with all kinds of software needed to run your application, but you still can debug it in the convenient way. As you understand – configuring the remote debug for any other server where you run your node application would be the same. You can debug your AWS or digitalocean node applications as well, just be sure, that the debug port is accessible from the PC where you run the WebStorm.
  • Степан Яковенко

    It doesn’t work for me, IDEA Ultimate can’t locate .js file and puts ‘unknown:12’ in the stack, when I put debugger keyword.

    • Well, that’s interesting. Are you doing it with Vagrant as well?

      In my case I was debugging the code, which was located in “synced_folder” for the Vagrant image. It could be, that, when debugging the remote application it’s less straightforward.

      Please, share your findings if you solve this issue.

      • Paca-vaca

        I’ve also have a problem with debugging node.js(express) application via webstorm. In my case I don’t use vagrant – the project work locally on my machine.

        • If you have your project locally, you don’t need to use remote debug.
          You need to configure the regular one, something like below:

          • Paca-vaca

            Thank you for this quick answer, but unfortunately I’ve tried something similar(without harmony flags). It starts the application but ignores the breaking points nevertheless.

          • Harmony flags are specific just in my case of course.

            For your case – try to make some simple node.js file (not the express app) and try to configure the debug for it. Check that everything works. Then you can use the knowledge to debug your larger app.

          • Paca-vaca

            Thank you for the advice – in the end the problem is with the generator-angular-fullstack )

    • Степан Яковенко

      Just in case it helps someone: in Webstorm it worked, in IDEA Ultimate it didn’t. Had no time to file a bug….

  • Mika

    Wow, thanks a lot, I was struggling with my vagrant setup to debug express app.
    Works great!

  • SanjithKumar

    How to debug the Coffee Script Project

    • unfortunately I don’t know as I don’t use Coffee Script. But, probably you can try to debug the compiled project.

  • Pingback: npm tasks debug in WebStorm - Pavel Polyakov's blog()

  • Cole Pacak

    Super straightforward. I don’t know why I had such a hard time with it before when your solution was so easy. Feels good to ditch all of those console.logs. Thanks!

  • Eran

    Thanks for the post. I can connect and debug. But, it seems to me that the highlighted line of code is not the real line being executed. Also, some breakpoints don’t work at some places in the code. It makes me think that my local code and the remote one might not be the same.

    But, the remote code is a docker container with my local code attached as an external volume – so it should be exactly the same.

    Might it be because I am using babel? I’m running node ./bin/www --exec babel-node. Maybe this changes the code and therefore the discrepancy?

    Any idea how can I deal with this?

    • Hi Eran,

      Yes, I think it might be connected to the babel issue, because babel transforms your code before you run it. But, from the other side – you don’t need to use babel for the back-end, in case you use node v6. Because it supports almost all the ES2015 features.

      So I would recommend you just to update the node version.

      • Eran

        Thank you Pavel! Yes, we might try that. The problem is that upgrading to a new major node version might break stuff. We have a significant code base, and it is not something I can easily affect immediately.

        Any idea if there is a way to tell webstorm to do a “reverse babel” matching so it could highlight the correct lines of code?