Debug your Node.js applications

Node.js provides a built-in debugger, known as Inspector, which provides a basic line-mode tool for debugging JavaScript code. It also provides a websockets interface in the Node.js runtime that supports more powerful GUI tools. A popular GUI tool to use with Node.js is the Chrome Developer Tools (DevTools) debugger, which is included in the Google Chrome browser.

This tutorial will help developers who are writing or maintaining Node.js JavaScript applications and need a fully functioning debugger to use during development and maintenance.

Note: The older node-inspector module, which is also referred to as Node Inspector, is now deprecated. Since Node.js version 6.3, the built-in debugger has provided more functionality and should be used instead.

The sample application used as an example is included at the end of this tutorial.

Learning objectives

After completing this project, you will understand how to:

  • Use a fully functioning debugger for development and maintenance
  • Begin using line-mode and GUI debuggers for Node.js
  • Use debuggers for Node.js applications running in IBM Cloud


Step 1: Using the Node.js line-mode debugger

  1. To start the line-mode debugger, run node inspect followed by your JavaScript application name. The debugger will pause your application at its starting point and open the command-line dialog with a debug prompt.

Now, type in commands to control the debug session and display information about the application. Typing the backtrace command, for example, prints a stack trace of the current program location.


Typing `help` at the debugger prompt returns a list of the available debugger commands, including their short-cut names.


When you run `node inspect`, Node.js spawns a child process to run your application with the --inspect flag, described below, and uses the main process to run the command-line debugger.

For a detailed description of the line-mode debugger commands, see the Node.js community documentation [here](

Step 2: Using the Chrome DevTools debugger

  1. To use the Chrome DevTools debugger, run your Node.js application with the --inspect option. You will see a Debugger listening message with a websocket URL, followed by a help message, just like when running the line-mode debugger. However, in this case, the debug command prompt does not appear.

  2. Attach the Chrome DevTools debugger to the application. The application continues to run until you attach the debugger. To pause the application at its initial starting point, use the --inspect-brk option instead of –inspect.

    C:\test>node --inspect simple.js
    Debugger listening on ws://
    For help, see [](

    C:\test>node --inspect-brk simple.js
    Debugger listening on ws://
    For help, see [](
  1. To attach the Chrome DevTools debugger to the application, open the URL chrome://inspect in the Google Chrome browser. Your application appears as a Remote Target on the DevTools Devices page, showing the name of your script. Click on Inspect to start the debugger.


    The debugger opens, and the source code of your application is shown. Because the application was started using the --inspect-brk option above, the application is paused with the first line of application code highlighted.

    Controls at the top right of the debugger window allow you to resume execution, step over, into or out of functions, deactivate breakpoints, and pause on exceptions.


  2. Set a breakpoint by clicking on a line number in the source code panel. In the example below, a breakpoint has been set on line 15, in the setInterval() function. Resume execution by clicking on the Control in the top right corner.

    At this point, what you see will match the diagram above where the setInterval() function has been triggered, and the application is now paused again at the required breakpoint. In the right-hand panel, examine the call stack and local variables.

    The console output from the application is shown in the panel at the bottom of the debugger window.


Step 3: Attaching the Developer Tools debugger to a running application

  1. On MacOS and Linux platforms, you can also attach the debugger to a running Node.js application, without specifying the --inspect option when you start the application. To do this, send the SIGUSR1 signal to the application process, using kill -USR1 <pid> command.

    The Debugger listening message is written to the console by Node.js when the signal is received. Then attach the Chrome DevTools debugger to the application as before, by opening chrome://inspect in the Google Chrome browser. The application appears as a Remote Target on the DevTools Devices page.

    Click on Inspect to start the debugger. When the debugger has attached to the application process, Node.js writes a Debugger attached message to the console.


    When you attach the Chrome DevTools debugger, the application will still be running. You can pause the application using the debugger controls or set a breakpoint so that the application pauses at a point that you are interested in debugging.

    In the example below, the application is paused at breakpoint set in a function that handles incoming HTTP requests. You can see details of the incoming message in the local variable display at the bottom right-hand side of the debugger window.


Sample Node.js application used in the examples

This example implements a simple HTTP server that responds with Hello World message on localhost port 8080. It also has an interval timer that issues a tick message to the console every 10 seconds.

// Node.js example application #1
var http = require('http')

http.createServer(function (req, res) {
  console.log('simple.js: request received')
  res.writeHead(200, {'Content-Type': 'text/plain'})
  res.end('Hello World\n')

console.log('simple.js: application listening on http://localhost:8080/')
console.log('simple.js: process id ' +

    console.log('simple.js: tick')
}, 10000);


You have now successfully learned how to use the Node.js line-mode debugger as well as the Chrome DevTools debugger and how to attach the debugger to a running application, allowing for better application writing and maintenance.