Logo
Back

How do I debug Node.js applications?

Debugging Node.js applications is essential for diagnosing issues, improving performance, and understanding application flow. Below are several techniques and tools—from simple console statements to more powerful debuggers like Chrome DevTools, VS Code, and third-party tools.

1. Using console.log (Quick Debugging)

Overview

  • The simplest way to debug is to insert console.log or console.error statements.
  • This approach can help you quickly see variable values, execution order, or detect errors in logic.
function processData(data) {
  console.log('Received data:', data);
  // ... rest of your code ...
}

Pros and Cons

  • Pros: No setup overhead, instant feedback.
  • Cons: Can clutter your code with logs, lacks interactive or step-by-step control.

2. Built-In Debugger (node inspect)

Node.js has a built-in debugger that you can invoke using node inspect:

node inspect index.js

Basic Commands:

  • n: Step to the next line
  • c: Continue execution until next breakpoint
  • sb(...): Set a breakpoint in a specific line or function

While this is powerful, it’s a bit barebones compared to full-featured debuggers in modern IDEs.

3. Chrome DevTools or Chromium-Based Debugger

Running Your App with the Debugger Flag

You can debug Node.js apps using Chrome DevTools (or Edge/Chromium) by launching Node with the --inspect or --inspect-brk flag:

# Start your Node app with the DevTools inspector enabled
node --inspect index.js

# or, to pause execution on the first line:
node --inspect-brk index.js

Node will print a URL (something like chrome-devtools://...) in the console. Open Chrome (or Edge), paste that URL into the address bar, and you’ll see:

  1. A Sources panel to set breakpoints, step through code, and evaluate variables.
  2. A Console to run commands or log out variables interactively.

Note:

  • --inspect attaches the debugger but starts executing immediately.
  • --inspect-brk breaks (pauses) on the first line of the script, letting you set breakpoints before any code runs.

4. Visual Studio Code Debugger

Integrated Debugging

VS Code offers a built-in debugger for Node.js:

  1. Open your Node.js project in VS Code.
  2. Create a launch configuration in .vscode/launch.json: 
    {
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      "program": "${workspaceFolder}/index.js",
      "skipFiles": [
        "<node_internals>/**"
      ]
    }
  ]
}
  3. Run the debugger by pressing F5 or selecting Run and Debug from the VS Code sidebar.

Setting Breakpoints

  • Place breakpoints in your code by clicking in the gutter next to the line numbers.
  • You can inspect variables, view call stacks, watch expressions, and step through code line by line.

5. Using Debugger; Statements

You can insert the debugger; statement in your code. When your debugger is attached (via --inspect or VS Code debug), the runtime will pause at that line:

function calculateTotal(cart) {
  debugger; // Execution will pause here when a debugger is attached
  // ... your logic ...
}

This lets you inspect variables right at the point of interest.

6. Nodemon for Auto-Restart During Debugging

When you’re making frequent changes, consider using Nodemon. It restarts the Node.js process each time you save a file.

npm install --global nodemon
nodemon --inspect index.js

You’ll still connect your debugger as usual, but now your server restarts automatically on file changes.

7. Remote Debugging

If your Node.js application runs on a remote server (e.g., cloud VM or container), you can still attach a debugger:

  1. Expose a port on the server (e.g., 9229 for --inspect).
  2. SSH Tunneling or use a secure connection to forward traffic from your local machine to the remote server’s debugger port.
  3. Attach your local Chrome DevTools or VS Code to localhost:9229 (after forwarding).

8. Third-Party Tools and Libraries

  • debug module: A popular library for managing debug log statements with namespaced categories: 
    const debug = require('debug')('app:routes');
debug('Got a request on /api');
  • PM2: A production process manager that includes some advanced monitoring.
  • Sentry / New Relic: For error tracking and performance profiling in production environments.

9. Common Debugging Strategies

  1. Watch Variables: Step through code to see how variables change over time.
  2. Check the Call Stack: Understand how your function was invoked and see the sequence of function calls leading to the current state.
  3. Use console.trace(): Logs a stack trace without stopping execution.
  4. Handle Uncaught Exceptions: Use process.on('uncaughtException', ...) or other error-handling logic to see stack traces for unhandled errors.

Recommended Resources

Conclusion

To debug Node.js applications effectively:

  • Start Simple: Use console.log or console.error for quick checks.
  • Leverage Built-In Debuggers: Use node --inspect with Chrome DevTools or Visual Studio Code’s integrated debugger for a more robust experience with breakpoints, watchers, and call stacks.
  • Automate and Scale: Add Nodemon for auto-restarting during development and consider remote debugging or third-party services for production monitoring.

A good debugging workflow drastically reduces development time and helps you produce cleaner, more reliable Node.js applications. Happy debugging!

CONTRIBUTOR
TechGrind