Enable the debugger on a running node process

Some errors in node processes only manifest themselves after the process has been running for an extended period of time. This post describes how to enable the debugger on a running node process.

Debugging node processes

The normal workflow for debugging a node process is to enable the debugger at startup by providing the --inspect command line argument. This will enable the debugger for the node process that is being started. It is now possible to attach the debugger interface to the running process by accessing chrome://inspect with Chrome or by attaching to the node process with an IDE that supports debugging node processes.

There is also an additional command line argument that will break at the first line of the script by specifying --inspect-brk in addition to the --inspect command line argument. The documentation of Node.js goes into more detail about this topic.

Debugging an already running node process

There exist some errors in programs that manifest themselves only after the process has been running for many days. Usually this will normally happen in production. Typically the debugger is not enabled on production and if the logging is not sufficient to find the cause of the error the only option to fix the issue is to restart the process and hope for it to never happen again or to periodically restart the process to prevent the issue to happen again.

Fortunately there exists the possibility to enable the debugger on an already running node process by sending the SIGUSR1 signal to the node process. This can also be done on a remotely running container. By forwarding the debugger port to your local machine you will also be able to connect the remotely running process and investigate the issue.

By using this technique I was able to track down the root cause of a setTimeout call with a delay parameter outside of the valid range. In a normally configured production environment node will not print a stack trace if that error occurs. Because setTimeout is one of the mosts used APIs of JavaScript it would have been impossible to track down the error in a library without being able to start the debugger on the already running node process.