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.

Header Image
Kotlin Development in VS Code

Kotlin is a really sweet language. It is the perfect thing in between a “super-powerful and but difficult language” like Rust or Modern C++, and a “super-easy but that seems to be designed in the 80s” …

Read
Header Image
My favorite Visual Studio Code extensions

Visual Studio Code is my editor of choice. I started with it because of the top-notch TypeScript integration, and then I stuck with it for all the rest (all but for big projects in languages with …

Read
Header Image
Debug with Git Binary Search

I don&rsquo;t think I have to spend too many words on Git. Every programmer who was not on the moon in the last 5 years should already be a proficient Git user. Git is an amazing, flexible and …

Read
comments powered by Disqus