Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท CLI Flags

Node.js NODE_DEBUG environment variable

Reference for NODE_DEBUG: turn on internal debug output for core modules such as http, net, fs and module, and add your own channels with util.debuglog().

NODE_DEBUG is a comma-separated list of debug channels. When a channel is listed, Node writes its internal diagnostic messages to standard error. Core modules define channels with names such as http, net, tls, stream, fs, module, child_process, timer and worker. It is a zero-code way to see what the runtime is doing: which module file was loaded, how a socket changed state, why a request was parsed the way it was.

You can create your own channels with util.debuglog(). They cost almost nothing when disabled, so libraries can keep many of them in production code.

NODE
// shell: NODE_DEBUG=http,net node server.js

Try it

Node.js Your own debug channel

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Watching the module loader

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
// NODE_DEBUG=channel1,channel2
// util.debuglog(section[, onFirstUse]): (msg, ...args) => void   (with .enabled)
// util.debug is an alias of util.debuglog
Name Description
NODE_DEBUG Comma-separated channel names. Matching ignores case. A trailing * matches any channel starting with that prefix.
section The channel name given to util.debuglog(). It is printed in upper case.
onFirstUse Optional callback that receives the logging function the first time it is called when enabled; handy for swapping in a smarter logger.

Returns: a function that formats like util.format() and writes SECTION pid: message to standard error. The function has a boolean enabled property, so you can skip expensive argument building.

Usage notes

  • Output goes to stderr, not stdout, so it does not corrupt piped program output.
  • Format: NAME pid: text. The process id makes lines from worker and child processes distinguishable; strip it when you compare output.
  • Read once at startup. Changing process.env.NODE_DEBUG later does nothing for channels already created. Set it in the shell, NODE_OPTIONS-style wrapper or child_process env.
  • Volume. http, net and stream produce a lot of lines under load. Turn them on for a short reproduction, never as a permanent setting.
  • Internal format is not an API. The text of core debug messages changes between releases. Use it to investigate, not to parse.
  • NODE_DEBUG_NATIVE is a separate variable for native C++ categories (for example NODE_DEBUG_NATIVE=fs) and is mostly useful when building Node itself.
  • For your own libraries, debuglog is the dependency-free alternative to the debug package. Use dotted names (mylib.pool) so a user can enable all with mylib*.
  • Not the inspector. NODE_DEBUG prints diagnostics; it does not attach a debugger. See --inspect for that.