Mastodon Icon RSS Icon GitHub Icon LinkedIn Icon RSS Icon

How to debug a Node.js application remotely in VSCode

Debugging a remote Node.js application in VSCode is an elementary procedure. Here it is a small “how to” in case you are struggling with it.

Quick Answer

Because I know you want just the answer, let’s skip for now all the background info.

  1. Run the remote application with the --inspect=PORT flag. For example,
1
node --inspect=9229 index.js
  1. In the app logs you should see something like Debugger listening on ws://127.0.0.1:9228/408a0f96-c43c-4b97-8bc6-a25eb55f9125. Save this address.
  2. On your local machine use SSH tunneling to map the remote port PORT into a local PORT with this command: ssh -L <LOCAL PORT>:127.0.0.1:<REMOTE PORT> <USERNAME>@<HOST>. For example:
1
ssh -L 9229:127.0.0.1:9229 ubuntu@my-aws-server`
  1. Now, with that terminal windows open, go to VSCode and reate a .vscode/launch.json file with this content:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
    "version": "0.2.0",
    "configurations": [
        {
            "address": "localhost:9229/408a0f96-c43c-4b97-8bc6-a25eb55f9125",
            "localRoot": "${workspaceFolder}",
            "name": "Attach to Remote",
            "port": 9229,
            "remoteRoot": "/path/to/remote/app/",
            "request": "attach",
            "skipFiles": [
                "<node_internals>/**"
            ],
            "type": "pwa-node"
        }
    ]
}
  1. Run the debug configuration on VSCode.
  1. You should now be able to connect to the remote app. Check on the status bar for confirmation.

A bit more info (if you want)

Every time I get a bug that I cannot reproduce locally, the only solution is to plug into the remote application and try to debug it. In my opinion, this is debugging 101, however I am surprised of how many people seem think that remote debugging is some kind of black magic. As you can see from the step above, it is a quite simple procedure.

The real game changer is SSH tunneling. With it, if you have SSH access to the remote machine then you can do remote debugging like it was local. This allows you to forget about complicated firewall and network rules (that you may or may not access or change).

I hope this is usefull. Cheers.