Node.js Debugging in VS Code and Chrome DevTools

Node.js debugging allows us to identify and fix errors, unexpected behavior, and performance issues in server-side JavaScript applications. Instead of using the less precise console.log, we can connect a real debugger and control execution step by step.

Most Node.js developers actually use one of two distinct setups:

• Visual Studio Code.
• Chrome DevTools.

This guide will show you how to use both technologies, with a clear step-by-step workflow for each. We’ll also show you how to inspect your code as it runs, so you can spot bugs that only appear under specific conditions.

Here’s the full list of contents.

What makes Node.js debugging different

Node.js debugging means we are debugging code that’s running in a server-side runtime, rather than inside the browser. This changes the setup, the tools, and the kinds of problems we need to inspect.

If you’ve previously used other debugging tools and techniques, these points can take some getting used to:

• The code runs outside Chrome by default.
• It usually needs --inspect or an attached debugger.
• It focuses on APIs, servers, scripts, and background jobs.
• It deals heavily with async flow, promises, and event loops.
• It has no visual UI to confirm what happened when things break.

In practice, we spend less time checking DOM events or layout issues and more time tracing execution state, request handling, and values moving through asynchronous code.

This helps us follow a request through the application and pinpoint exactly where its behaviour veers off from what we expect.

Debug Node.js in Visual Studio Code

Visual Studio Code lets us control execution line by line instead of relying on logs.

It runs our app with a debugger attached, so we can pause execution, inspect values, and understand exactly how the code behaves in real time.

This is particularly useful for complex logic and repeatable workflows, where we need full visibility without constantly restarting or modifying the code.

How to debug Node.js in Visual Studio Code

1. Set up debug configuration

First, you need a debug configuration so Visual Studio Code can run your Node.js app in debug mode.

Here are the steps to follow:

1. Open the Run and Debug panel (left sidebar).
2. Click “create a launch.json file”.
3. Select Node.js as the environment.
4. Set the program field to your entry file (e.g. app.js).
5. Save the file and keep default settings unless needed.

You normally only need to create this configuration once for the project. Afterwards, you can start debugging with a single click instead of running manual commands every time.

2. Start the debug session

Now you can run your Node.js app with Visual Studio Code’s built-in debugger attached. Here’s how:

1. Open the Run and Debug panel.
2. Select your configuration (e.g. “Launch Program”).
3. Click the green Start Debugging button or press F5.
4. Wait for Visual Studio Code to launch the process with the debugger connected.

Your code is now running in debug mode. Execution will pause automatically when the code hits a breakpoint, allowing you to inspect and control what happens next.

3. Set breakpoints

Breakpoints let you pause execution exactly where you want to inspect your code. If you suspect that your Node.js app is failing at a specific line, breakpoints allow you to zoom in on that perceived point of failure.

To set breakpoints, simply follow these steps:

1. Open your file in Visual Studio Code.
2. Click into the left margin next to a line number.
3. Add breakpoints on critical logic or suspected issues.
4. Start or continue the debug session.

Execution will stop when it reaches the line you’ve chosen.

4. Inspect variables and call stack

This is where most bugs become obvious. The point where you get to see the current state of your program, and the steps it took to reach this point.

• Variables show you the current data, so you can identify missing or incorrect values.
• The call stack shows the active chain of function calls that led to the current execution point, helping you trace where an unexpected value or behaviour originated.

Here’s what you need to do:

1. Pause execution on a breakpoint in Visual Studio Code.
2. Check the Variables panel to see current values.
3. Expand objects to inspect nested data.
4. View the Call Stack to trace the execution path.
5. Hover over variables in the editor for quick previews.

5. Attach to running process

Sometimes, we need to attach VS Code to a Node.js app that’s already running with the Inspector enabled, rather than launch it directly from VS Code.

Why? Because we can set breakpoints and inspect the process in its current state and runtime environment, and see the problem the moment it occurs rather than trying to reconstruct it afterwards.

This is particularly useful for server issues, background jobs, and bugs that only appear after an application has been running for some time.

1. Start your app with debug mode enabled (-inspect).
2. Open the Run and Debug panel.
3. Select an Attach configuration in launch.json .
4. Click Start Debugging or press F5.
5. Choose the running Node.js process if prompted.

Debug Node.js in Chrome DevTools

While Visual Studio Code is a stand-alone code editor with built-in debugging tools, Chrome DevTools provides a browser-based debugging interface. For those who are new – you can connect to a running Node.js process and inspect its execution directly within Chrome.

This is great for quick debugging sessions, remote environments, or when you want to inspect runtime behavior without setting up a full development workspace.

How to debug Node.js in Chrome DevTools

1. Start Node.js in debug mode and connect Chrome DevTools

This makes your backend visible inside DevTools and gives you the power to control execution.

Here are the steps:

1. Run your app with node --inspect app.js.
2. Open Chrome and go to chrome://inspect.
3. Click “Open dedicated DevTools for Node”.
4. Select your running process under Remote Target.
5. Wait for DevTools to attach.

DevTools is now connected to your Node process. You can pause execution, set breakpoints, and inspect runtime behavior directly from Chrome, so there’s no need for a separate VS Code-style launch step. We can skip straight through to breakpoints.

2. Set breakpoints and step through code

As we mentioned previously, setting breakpoints allows you to pause execution, analyze your Node.js code step by step and follow the exact flow of your program, pausing execution exactly where you want to.

The steps are slightly different for DevTools than for VS Code, so pay close attention here.

1. Open the Sources panel in DevTools.
2. Locate your file under the Node.js section.
3. Click the line number to add a breakpoint.
4. Trigger the code path you want to debug.
5. Use step controls (step over, into, out) to move through execution.

3. Inspect variables and call stack

Just as with the VS Code workflow, this stage allows you to see what your Node.js app is doing in real time and examine the exact state of your application. This can help you identify logic errors, undefined values, and unexpected data.

Again, there’s a slight variation in the steps here, primarily in step 2.

1. Pause execution on a breakpoint
2. Open the Scope panel to view local and global variables
3. Expand objects to inspect nested values
4. Check the Call Stack to understand how execution reached that point
5. Hover variables in the editor for quick previews

4. Inspect runtime behavior and performance

Here the steps differ quite sharply from VS Code, but the benefit is the same. Inspecting runtime behavior and performance in Chrome DevTools lets you understand how your Node.js app actually runs over time, so you can catch slow operations, blocking code, and unexpected execution patterns.

1. Open the Performance panel in DevTools.
2. Start a recording while your code runs.
3. Trigger the operation you want to analyze.
4. Stop recording and review the timeline.
5. Identify CPU-intensive functions and execution hotspots that may be slowing the application or blocking the event loop.

Troubleshoot Node.js debugging issues

Many problems with the Node.js debugging setup come from configuration or connection issues rather than the application code itself. Fixing them is usually about identifying what failed in the debug setup.

Issue	What to check
Breakpoints not working	File path matches, source maps enabled
Debugger not connecting	Correct port (9229), --inspect active
Wrong file running	program points to correct entry file
Code not updating	Restart process, disable caching tools
Port already in use	Kill process or change debug port
App not starting	Check Node version and dependencies

Most problems are solved by checking configuration first. Before changing any code, verify how the debugger is attached and how the app is being executed.

Node.js remote debugging with Bugfender

Node.js remote debugging means connecting your debugger to an app running on another machine, not your local environment.

This is used for servers, containers, or staging setups where issues don’t appear locally.

1. Start the app in debug mode on the remote server.
2. Expose the debug port or create an SSH tunnel.
3. Connect from VS Code or Chrome DevTools.
4. Debug the app as if it were local.

This setup solves the classic “works locally but breaks on server” problem.

If opening ports is not possible, tools like Bugfender (and yes, this is our tool!) **let you inspect logs and behavior remotely without direct access.

You can try Bugfender here: https://dashboard.bugfender.com/signup

To sum up

Good debugging is not about tools. It is about visibility and control.

Once you can pause execution and inspect real values, most issues stop being “bugs” and become simple state problems you can trace and fix.

The fastest workflow is the one you can repeat without thinking. Set up your debugger once, reuse it every time, and remember: no guess, no matter how educated, is better than evidence you can see with your own eyes.

Node.js debugging FAQs

How do I start Node.js in debug mode?

Start Node.js in debug mode by running your app with node --inspect app.js.

This enables the Node.js Inspector and opens a port that debugging clients such as VS Code or Chrome DevTools can connect to.

If you want to pause execution immediately, use --inspect-brk instead so you can debug from the first line.

Can I debug Node.js without VS Code?

Yes, you can debug Node.js without Visual Studio Code by using Chrome DevTools or other debuggers.

Node.js supports the Inspector protocol, which allows multiple tools to attach and control execution.

VS Code is convenient, but Chrome DevTools or terminal-based tools can handle most debugging tasks as well.

How do I debug a Node.js server?

Debug a Node.js server by running it in debug mode and attaching a debugger to the running process.

Start the server with --inspect, then connect using VS Code or Chrome DevTools.

For remote servers, expose the debug port or use an SSH tunnel to connect securely and debug the app as if it were local.