Enable inspector
When started with the--inspect switch, a Node.js process listens for a
debugging client. By default, it will listen at host and port 127.0.0.1:9229.
Each process is also assigned a unique UUID.
Inspector clients must know and specify host address, port, and UUID to connect.
A full URL will look something like:
SIGUSR1 signal. (SIGUSR1 is not available on Windows.) In Node.js 7 and
earlier, this activates the legacy Debugger API. In Node.js 8 and later, it will
activate the Inspector API.
Live debugging
In a local environment, live debugging means attaching a debugger to your application, adding breakpoints to suspend program execution, and stepping through code paths to inspect values held in memory. Using a live debugger in production is usually not an option because you have limited access to the machine and cannot interrupt execution of a business-critical workload.Symptoms that call for live debugging
Your application does not provide the expected output for certain inputs — for example, an HTTP server returns a JSON response where certain fields are empty. In this situation you want to:- Understand the code path executed for a given trigger (such as an incoming HTTP request).
- Step through the code and control execution.
- Inspect what values variables hold in memory.
Security implications
Since the debugger has full access to the Node.js execution environment, a malicious actor able to connect to this port may be able to execute arbitrary code on behalf of the Node.js process. It is important to understand the security implications of exposing the debugger port on public and private networks.Exposing the debug port publicly is unsafe
By defaultnode --inspect binds to 127.0.0.1. You explicitly need to provide a
public IP address or 0.0.0.0 if you intend to allow external connections
to the debugger. Doing so may expose you to a potentially significant security
threat. Ensure appropriate firewalls and access controls are in place
to prevent a security exposure.
See Enabling remote debugging scenarios for advice on how
to safely allow remote debugger clients to connect.
Local applications have full access to the inspector
Even if you bind the inspector port to127.0.0.1 (the default), any applications
running locally on your machine will have unrestricted access. This is by design
to allow local debuggers to attach conveniently.
Browsers, WebSockets and same-origin policy
Websites open in a web browser can make WebSocket and HTTP requests under the browser security model. An initial HTTP connection is necessary to obtain a unique debugger session id. The same-origin policy prevents websites from being able to make this HTTP connection. For additional security against DNS rebinding attacks, Node.js verifies that theHost headers for the connection specify either an IP address
or localhost precisely.
These security policies disallow connecting to a remote debug server by
specifying the hostname. You can work around this restriction by specifying
either the IP address or by using SSH tunnels as described below.
Inspector clients
A minimal CLI debugger is available withnode inspect myscript.js.
Several commercial and open source tools can also connect to the Node.js inspector.
Chrome DevTools 55+ and Microsoft Edge
Chrome DevTools 55+ and Microsoft Edge
Option 1: Use the built-in DevTools UISee Chrome DevTools Frontend and Microsoft Edge DevTools Guide for more information.
Option 2: Connect manually
Get the frontend URL
Visit
http://localhost:<inspect-port>/json/list. It should return a JSON object containing a devtoolsFrontendUrl.Visual Studio Code 1.10+
Visual Studio Code 1.10+
In the Debug panel, click the settings icon to open
.vscode/launch.json and select Node.js for initial setup.See VS Code Node.js debugging for more information.Visual Studio 2017+
Visual Studio 2017+
Choose Debug > Start Debugging from the menu or press
F5.See the detailed instructions for more information.JetBrains WebStorm and other JetBrains IDEs
JetBrains WebStorm and other JetBrains IDEs
Create a new Node.js debug configuration and click Debug.
--inspect is used
by default for Node.js 7+. To disable it, uncheck js.debugger.node.use.inspect in
the IDE Registry.See WebStorm online help for more information.chrome-remote-interface
chrome-remote-interface
A library that eases connections to Inspector Protocol endpoints.See chrome-remote-interface on GitHub for more information.
Eclipse IDE with Eclipse Wild Web Developer extension
Eclipse IDE with Eclipse Wild Web Developer extension
From a
.js file, choose Debug As… > Node program, or create a Debug
Configuration to attach the debugger to a running Node.js application (already
started with --inspect).See eclipseide.org for more information.Command-line options
The following table lists the impact of various runtime flags on debugging:| Flag | Meaning |
|---|---|
--inspect | Enable inspector agent; listen on default address and port (127.0.0.1:9229) |
--inspect=[host:port] | Enable inspector agent; bind to address or hostname host (default: 127.0.0.1); listen on port port (default: 9229) |
--inspect-brk | Enable inspector agent; listen on default address and port (127.0.0.1:9229); break before user code starts |
--inspect-brk=[host:port] | Enable inspector agent; bind to address or hostname host (default: 127.0.0.1); listen on port port (default: 9229); break before user code starts |
--inspect-wait | Enable inspector agent; listen on default address and port (127.0.0.1:9229); wait for debugger to be attached |
--inspect-wait=[host:port] | Enable inspector agent; bind to address or hostname host (default: 127.0.0.1); listen on port port (default: 9229); wait for debugger to be attached |
--disable-sigusr1 | Disable the ability to start a debugging session by sending a SIGUSR1 signal to the process |
node inspect script.js | Spawn child process to run user’s script under --inspect flag; use main process to run CLI debugger |
node inspect --port=xxxx script.js | Spawn child process to run user’s script under --inspect flag; use main process to run CLI debugger; listen on port port (default: 9229) |
Enabling remote debugging scenarios
The following example is for illustrative purposes only. Understand the security risk of allowing remote access to a privileged service before proceeding. Assume you are running Node.js on a remote machine,remote.example.com, that
you want to debug. On that machine, start the node process with the inspector
listening only on localhost (the default):
9221 on your local
machine will be forwarded to port 9229 on remote.example.com. You can now
attach a debugger such as Chrome DevTools or Visual Studio Code to
localhost:9221, which will debug as if the Node.js application were running
locally.
Legacy debugger
When started with the--debug or --debug-brk switches in version 7 and
earlier, Node.js listens for debugging commands defined by the discontinued
V8 Debugging Protocol on a TCP port (default: 5858). Any debugger client
that speaks this protocol can connect to and debug the running process.
The V8 Debugging Protocol is no longer maintained or documented.
Built-in debugger
Startnode debug script_name.js to start your script under the built-in
command-line debugger. Your script starts in another Node.js process started
with the --debug-brk option, and the initial Node.js process runs the
_debugger.js script and connects to your target.
See the debugger docs for more information.