Master Remote Node.js Debugging: Built‑in Tools, VSCode, and node‑inspector

Introduction

Node.js debugging can be performed in three main ways: the built‑in debugger, IDE integration (e.g., VSCode), and the third‑party node‑inspector. This article focuses on how to debug Node code running on a remote server using node‑inspector.

Method 1: Built‑in Debugger

Start debugging at the first line

node debug app.js

Start debugging at a specific line

For example, set a breakpoint at line 3 using debugger or sb(line).

Step commands

Next step: next Continue to next breakpoint: cont Inspect variable: repl then type the variable name, exit with ctrl+c Add/remove watch: watch(expr), watchers, unwatch(expr) Step into/out of functions: step / s and out / o Example code:

var nick = 'chyingp';
var country = 'China';
var str = nick + ' live in ' + country;
var logger = function(msg){
    console.log(msg); // here
    console.log('this line will be skipped'); // skipped
};
logger(str); // breakpoint here
console.log(str);

Multiple file breakpoints

Use setBreakpoint('script.js', 1) or sb(...) to set breakpoints across files.

Restarting

Instead of relaunching with node debug app.js each time, use restart.

Remote debugging

On the remote machine (IP 192.168.1.126) start the debugger:

[root@localhost ex]# node --debug-brk app.js
Debugger listening on port 5858

Then connect from the local machine: node debug 192.168.1.126:5858 Sample session:

➜ /tmp node debug 192.168.1.126:5858
connecting to 192.168.1.126:5858 ... ok
break in /tmp/ex/app.js:1
> 1 var Logger = require('./logger');
  2 
  3 Logger.info('hello');
debug> n
break in /tmp/ex/app.js:3
  1 var Logger = require('./logger');
  2 
> 3 Logger.info('hello');
  4 
  5 });

Debugging can also be performed via PID (not shown).

Method 2: Debugging with VSCode

Open the project in VSCode, add a launch configuration pointing to the executable, set breakpoints in the editor, and start debugging. The UI shows variables, watch expressions, and a toolbar similar to Chrome DevTools.

Method 3: Using node‑inspector

Install globally:

npm install -g node-inspector

Option 1: node-debug

Run:

node-debug app.js
Node Inspector v0.12.8
Visit http://127.0.0.1:8080/?port=5858 to start debugging.
Debugger listening on port 5858

The browser opens the debugging UI.

Option 2: Manual workflow

Start the inspector server: node-inspector Launch the app with --debug-brk to pause at the first line.

Open the printed URL (e.g., http://127.0.0.1:8080/?port=5858) in a browser.

How it works

node --debug-brk

opens V8 debugger on port 5858. node‑inspector serves a web UI on port 8080.

The UI communicates with the inspector service via WebSocket, sending commands such as setting breakpoints, which the V8 debugger executes.

Internally it uses the v8‑debug module.

Remote debugging with node‑inspector

Example: run app.js on an Alibaba Cloud server (IP xxx.xxx.xxx.xxx). On the server start node‑inspector, then launch the app with --debug‑brk. Finally, from a local machine open the UI URL to debug.

Common issue: security restrictions

Remote debugging may be blocked by firewall rules. Open port 8080 (or the chosen UI port) using firewall‑cmd --add‑port=8080/tcp or iptables.

Related Links

Node Debugger Documentation

How Does a C Debugger Work?

How Debuggers Work: Part 2 – Breakpoints