The Node.js® Website
keii.dev
1---
2title: Debugging Node.js
3layout: learn
4---
5
6# Debugging Node.js
7
8This guide will help you get started debugging your Node.js apps and scripts.
9
10## Enable Inspector
11
12When started with the `--inspect` switch, a Node.js process listens for a
13debugging client. By default, it will listen at host and port 127.0.0.1:9229.
14Each process is also assigned a unique [UUID][].
15
16Inspector clients must know and specify host address, port, and UUID to connect.
17A full URL will look something like
18`ws://127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e`.
19
20Node.js will also start listening for debugging messages if it receives a
21`SIGUSR1` signal. (`SIGUSR1` is not available on Windows.) In Node.js 7 and
22earlier, this activates the legacy Debugger API. In Node.js 8 and later, it will
23activate the Inspector API.
24
25## Security Implications
26
27Since the debugger has full access to the Node.js execution environment, a
28malicious actor able to connect to this port may be able to execute arbitrary
29code on behalf of the Node.js process. It is important to understand the security
30implications of exposing the debugger port on public and private networks.
31
32### Exposing the debug port publicly is unsafe
33
34If the debugger is bound to a public IP address, or to 0.0.0.0, any clients that
35can reach your IP address will be able to connect to the debugger without any
36restriction and will be able to run arbitrary code.
37
38By default `node --inspect` binds to 127.0.0.1. You explicitly need to provide a
39public IP address or 0.0.0.0, etc., if you intend to allow external connections
40to the debugger. Doing so may expose you to a potentially significant security
41threat. We suggest you ensure appropriate firewalls and access controls in place
42to prevent a security exposure.
43
44See the section on '[Enabling remote debugging scenarios](#enabling-remote-debugging-scenarios)' on some advice on how
45to safely allow remote debugger clients to connect.
46
47### Local applications have full access to the inspector
48
49Even if you bind the inspector port to 127.0.0.1 (the default), any applications
50running locally on your machine will have unrestricted access. This is by design
51to allow local debuggers to be able to attach conveniently.
52
53### Browsers, WebSockets and same-origin policy
54
55Websites open in a web-browser can make WebSocket and HTTP requests under the
56browser security model. An initial HTTP connection is necessary to obtain a
57unique debugger session id. The same-origin-policy prevents websites from being
58able to make this HTTP connection. For additional security against
59[DNS rebinding attacks](https://en.wikipedia.org/wiki/DNS_rebinding), Node.js
60verifies that the 'Host' headers for the connection either
61specify an IP address or `localhost` precisely.
62
63These security policies disallow connecting to a remote debug server by
64specifying the hostname. You can work-around this restriction by specifying
65either the IP address or by using ssh tunnels as described below.
66
67## Inspector Clients
68
69A minimal CLI debugger is available with `node inspect myscript.js`.
70Several commercial and open source tools can also connect to the Node.js Inspector.
71
72### [Chrome DevTools](https://github.com/ChromeDevTools/devtools-frontend) 55+, [Microsoft Edge](https://www.microsoftedgeinsider.com)
73
74- **Option 1**: Open `chrome://inspect` in a Chromium-based
75 browser or `edge://inspect` in Edge. Click the Configure button and ensure your target host and port
76 are listed.
77- **Option 2**: Copy the `devtoolsFrontendUrl` from the output of `/json/list`
78 (see above) or the --inspect hint text and paste into Chrome.
79
80> Note that the Node.js and the Chrome need to be run on the same platform.
81
82### [Visual Studio Code](https://github.com/microsoft/vscode) 1.10+
83
84- In the Debug panel, click the settings icon to open `.vscode/launch.json`.
85 Select "Node.js" for initial setup.
86
87### [Visual Studio](https://github.com/Microsoft/nodejstools) 2017+
88
89- Choose "Debug > Start Debugging" from the menu or hit F5.
90- [Detailed instructions](https://github.com/Microsoft/nodejstools/wiki/Debugging).
91
92### [JetBrains WebStorm](https://www.jetbrains.com/webstorm/) and other JetBrains IDEs
93
94- Create a new Node.js debug configuration and hit Debug. `--inspect` will be used
95 by default for Node.js 7+. To disable uncheck `js.debugger.node.use.inspect` in
96 the IDE Registry. To learn more about running and debugging Node.js in WebStorm and other JetBrains IDEs,
97 check out [WebStorm online help](https://www.jetbrains.com/help/webstorm/running-and-debugging-node-js.html).
98
99### [chrome-remote-interface](https://github.com/cyrus-and/chrome-remote-interface)
100
101- Library to ease connections to [Inspector Protocol][] endpoints.
102
103### [Gitpod](https://www.gitpod.io)
104
105- Start a Node.js debug configuration from the `Debug` view or hit `F5`. [Detailed instructions](https://medium.com/gitpod/debugging-node-js-applications-in-theia-76c94c76f0a1)
106
107### [Eclipse IDE](https://eclipse.org/eclipseide) with Eclipse Wild Web Developer extension
108
109- From a .js file, choose "Debug As... > Node program", or
110- Create a Debug Configuration to attach debugger to running Node.js application (already started with `--inspect`).
111
112## Command-line options
113
114The following table lists the impact of various runtime flags on debugging:
115
116| Flag | Meaning |
117| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
118| --inspect | Enable inspector agent; Listen on default address and port (127.0.0.1:9229) |
119| --inspect=[host:port] | Enable inspector agent; Bind to address or hostname host (default: 127.0.0.1); Listen on port port (default: 9229) |
120| --inspect-brk | Enable inspector agent; Listen on default address and port (127.0.0.1:9229); Break before user code starts |
121| --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 |
122| node inspect script.js | Spawn child process to run user's script under --inspect flag; and use main process to run CLI debugger. |
123| node inspect --port=xxxx script.js | Spawn child process to run user's script under --inspect flag; and use main process to run CLI debugger. Listen on port port (default: 9229) |
124
125## Enabling remote debugging scenarios
126
127We recommend that you never have the debugger listen on a public IP address. If
128you need to allow remote debugging connections we recommend the use of ssh
129tunnels instead. We provide the following example for illustrative purposes only.
130Please understand the security risk of allowing remote access to a privileged
131service before proceeding.
132
133Let's say you are running Node.js on a remote machine, remote.example.com, that
134you want to be able to debug. On that machine, you should start the node process
135with the inspector listening only to localhost (the default).
136
137```bash
138node --inspect server.js
139```
140
141Now, on your local machine from where you want to initiate a debug client
142connection, you can setup an ssh tunnel:
143
144```bash
145ssh -L 9221:localhost:9229 user@remote.example.com
146```
147
148This starts a ssh tunnel session where a connection to port 9221 on your local
149machine will be forwarded to port 9229 on remote.example.com. You can now attach
150a debugger such as Chrome DevTools or Visual Studio Code to localhost:9221,
151which should be able to debug as if the Node.js application was running locally.
152
153## Legacy Debugger
154
155**The legacy debugger has been deprecated as of Node.js 7.7.0. Please use
156`--inspect` and Inspector instead.**
157
158When started with the **--debug** or **--debug-brk** switches in version 7 and
159earlier, Node.js listens for debugging commands defined by the discontinued
160V8 Debugging Protocol on a TCP port, by default `5858`. Any debugger client
161which speaks this protocol can connect to and debug the running process; a
162couple popular ones are listed below.
163
164The V8 Debugging Protocol is no longer maintained or documented.
165
166### [Built-in Debugger](https://nodejs.org/dist/latest/docs/api/debugger.html)
167
168Start `node debug script_name.js` to start your script under the builtin
169command-line debugger. Your script starts in another Node.js process started with
170the `--debug-brk` option, and the initial Node.js process runs the `_debugger.js`
171script and connects to your target.
172
173### [node-inspector](https://github.com/node-inspector/node-inspector)
174
175Debug your Node.js app with Chrome DevTools by using an intermediary process
176which translates the [Inspector Protocol][] used in Chromium to the V8 Debugger
177protocol used in Node.js.
178
179[Inspector Protocol]: https://chromedevtools.github.io/debugger-protocol-viewer/v8/
180[UUID]: https://tools.ietf.org/html/rfc4122