Using Node's NODE_DEBUG for fun and profit

The NODE_DEBUG environment variable can be used to enable debug logs for some Node’s internal modules. It gives you a lot of information about what these modules are actually doing. This is very helpful in many different common cases, like when you’re stuck on a module loading issue.

To use NODE_DEBUG, simply set its value to a list of internal module names, each identifying a module which you want to log debug information for.

For instance, starting the Node.js interpreter with the following command line

NODE_DEBUG=module node

will enable debug logs in the internal module named module. Since this module is responsible for handling the loading of modules, you can get detailed information about what modules are loaded from where on your filesystem. This can be very handy when troubleshooting a module loading issue.

Unfortunately, not all internal modules support enabling debug logs using NODE_DEBUG. Currently, here’s the list of supported modules:

For instance, you can enable debug logs for all these modules using the following command:

NODE_DEBUG=cluster,net,http,fs,tls,module,timers node

However, some of these modules will display a lot of information, and unless you really need to troubleshoot all of them at the same time, I recommend picking the one that is related to the issue you’re currently investigating.

Note that you don’t need to use a comma to separate the internal modules’ names when setting NODE_DEBUG, you can choose whatever separator you want, or even no separator at all.

I invite you to play with these modules and the NODE_DEBUG environment variable. It can be a good way to better understand how these internal modules work. Sometimes, like with the net and tls modules, it can also help you understand how sockets and TLS work. Finally, I also hope it will help you troubleshoot issues you may have when developping Node.js apps.

Julien Gilli 26 May 2013
blog comments powered by Disqus