1708

How do I debug a Node.js server application?

Right now I'm mostly using alert debugging with print statements like this:

sys.puts(sys.inspect(someVariable));

There must be a better way to debug. I know that Google Chrome has a command-line debugger. Is this debugger available for Node.js as well?

7

42 Answers 42

1308
+50

node-inspector could save the day! Use it from any browser supporting WebSocket. Breakpoints, profiler, livecoding, etc... It is really awesome.

Install it with:

npm install -g node-inspector

Then run:

node-debug app.js
17
  • 15
    Wish node-inspector was active. The profiling component needs to get some love. Dec 5, 2011 at 0:32
  • 15
    Unfortunately for me, node-inspector doesn't work with the latest versions of Node.js and it hasn't supported logging to the browser console since v0.1. node-codein was just buggy. So, I wrote my own module to help with debugging by allowing you to dump objects and such out to your web browser console. I thought it may be of use to someone else: node-monkey. Plus it works in both Firefox AND Chrome. Oct 20, 2012 at 3:17
  • 7
    Since this was such an apparently amazing and popular tool, surely the fact that the original author has admitted they no longer have the resources to maintain it wouldn't be a problem as the open source community could pick it up?
    – PeterT
    Mar 21, 2013 at 18:13
  • 34
    Now inspector is now actively maintained by StrongLoop and is working again with the latest version (0.3) yay! Announcement here: blog.strongloop.com/…
    – balupton
    Jul 25, 2013 at 15:31
  • 29
    "Since version 6.3, Node.js provides a buit-in DevTools-based debugger which mostly deprecates Node Inspector, see e.g. this blog post to get started. The built-in debugger is developed directly by the V8/Chromium team and provides certain advanced features (e.g. long/async stack traces) that are too difficult to implement in Node Inspector." - says the node inspector repo
    – ThisClark
    Jun 4, 2017 at 0:31
794

Debugging

Profiling

  1. node --prof ./app.js
  2. node --prof-process ./the-generated-log-file

Heapdumps

Flamegraphs

Tracing

Logging

Libraries that output debugging information

Libraries that enhance stack trace information

Benchmarking

Other

Legacy

These use to work but are no longer maintained or no longer applicable to modern node versions.

9
  • 8
    About Nodetime: for those who don't want to send their data to nodetime servers there's a local "alternative" (it's still based on nodetime), the look module, as pointed out in stackoverflow.com/questions/12864221/nodejs-memory-profiling
    – reallynice
    Oct 25, 2013 at 12:28
  • I don't find the cpu reports from nodetime very helpful: 1. I just get a tree of methods, with no 'self' time. 2. Seems like the tree branches are trimmed below a certain number of precentage. Those 2 makes it very difficult to undestand where the cpu spends most of its time.
    – shacharz
    Jul 20, 2014 at 12:09
  • npm install -g profiler complains about missing python on windows 7. I tried to set python=C:\Python34\, but this gives a crash. Sep 8, 2014 at 12:45
  • The only profiler working out of the box is nodetime. But its cpu profiling stacktrace is unusable (it doesn't give enough details). Nodejs tools 4 msvc 2012 also have profiler, but it also has reported critical unfixed bug... Sep 8, 2014 at 12:47
  • The only profiler that worked for me was nprof + v8.log from node --prof. Jan 9, 2015 at 1:07
269

The V8 debugger released as part of the Google Chrome Developer Tools can be used to debug Node.js scripts. A detailed explanation of how this works can be found in the Node.js GitHub wiki.

7
  • 12
    I'm interested, after the presentation at Google IO that Paul Irish and Pavel did is it now possible to debug node.js straight to Chrome Developer Tools without the need for eclipse?
    – balupton
    May 19, 2011 at 20:35
  • +1 Worked very well for me. Using a fresh Eclipse 3.x, x64 version on Mac OS X. The installation instructions are well written as well. Thank you. Jan 6, 2012 at 16:40
  • Also comes within Nodeclipse nodeclipse.org (with some Node.js related bugs fixed) Jun 16, 2013 at 15:53
  • My entry into this arena is trepanjs (npmjs.com/package/trepanjs). It has all of the goodness of the node debugger, but conforms better to gdb. It also has more features and commands like syntax highlighting, more extensive online help, and smarter evaluation. See github.com/rocky/trepanjs/wiki/Cool-things for some of its cool features.
    – rocky
    May 18, 2015 at 22:04
  • 1
    The feature is currently available in the nightly versions. Check out here for instructions: https://medium.com/@paul_irish/debugging-node-js-nightlies-with-chrome-devtools-7c4a1b95ae27#.fitvuaumt
    – zeronone
    Jul 5, 2016 at 2:25
214

Node has its own built in GUI debugger as of version 6.3 (using Chrome's DevTools)

Nodes builtin GUI debugger

Simply pass the inspector flag and you'll be provided with a URL to the inspector:

node --inspect server.js

You can also break on the first line by passing --inspect-brk instead.

8
  • 2
    Not to discount the steps above, but just to share... I attempted to create a wrapper that is slightly more robust, as well as easier to install. See: github.com/jaridmargolin/inspect-process Nov 17, 2016 at 22:30
  • 1
    @JaridR.Margolin Nice. I updated the answer to use that instead. A lot easier to setup and works better :)
    – gregers
    Dec 13, 2016 at 10:31
  • 2
    This answer is currently at the bottom and it's the only one that has actually worked for me. This is flipping awesome!
    – LOAS
    Jan 2, 2017 at 10:44
  • 3
    In case it helps anyone, I threw up a video explaining this process at youtu.be/rtZKUnks6jI.
    – RoccoB
    Mar 23, 2017 at 18:15
  • 1
    For node 6.x, use node --inspect --debug-brk server.js to automatically stop on the first line.
    – Mike Post
    Nov 11, 2017 at 14:09
97

Node.js version 0.3.4+ has built-in debugging support.

node debug script.js

Manual: http://nodejs.org/api/debugger.html

7
  • 1
    Do you have any links to documentation of how to use it? Jan 16, 2011 at 12:17
  • 2
    I don't have any docs. just updated to v0.3.5. put a line "debugger;" in your code which will act as break point. It works like ndb / gdb. after you do "node debug script.js" type help. u will see the command it support. p = print, l = list... so you don't need to type the full world
    – JulianW
    Jan 20, 2011 at 23:59
  • 2
    Note, under windows it's "node.exe --debug myscript.js" but it still don't work.
    – Marc
    Sep 6, 2011 at 12:13
  • 6
    You probably have to change --debug to debug without the dashes. That's how I finally got it to work. It's confusing that --debug and debug do two different things.
    – benekastah
    Oct 7, 2011 at 5:55
  • How do you get the program to actually run? "r -> app is already running...", when i try to continue and i run into a statement that is trying to get input it drops me back at the debug prompt instead of letting me enter the input that is required.
    – Michael
    Jul 11, 2016 at 23:22
77

Visual Studio Code will be my choice for debugging. No overhead of installing any tools or npm install stuff. Just set the starting point of your app in package.json and VSCode will automatically create a configuration file inside your solution. It's build on Electron, on which editors like Atom are built.

VS Code gives similar debugging experience as you might have had in other IDEs like VS, Eclipse, etc.

enter image description here enter image description here

5
  • It's cool but it has lag. That's why I do prefer Sublime ever.
    – calbertts
    May 24, 2017 at 21:48
  • 3
    but sublime doesn't have a debugger,and i think VS code is pretty fast too Oct 27, 2017 at 10:35
  • 1
    I've a sublime license since 5 years ago. Since a few months ago I don't even install Sublime Text, just vscode. Out of the box has a lot of tools which I miss in Sublime (like the integrated terminal..). Mar 19, 2018 at 13:22
  • always asking me for a config folder, it doesn't work out of the box
    – carkod
    Jun 18, 2018 at 14:55
  • @carkod enable vs code auto attach preference and use the vs code terminal to start your script, ex node --inspect file-name.js Dec 25, 2019 at 11:16
61

I personally use JetBrains WebStorm as it's the only JavaScript IDE that I've found which is great for both frontend and backend JavaScript.

It works on multiple OS's and has Node.js debugging built-in (as well as a ton of other stuff](http://www.jetbrains.com/webstorm/features/index.html).

My only 'issues'/wishlist items are were:

  1. It seems to be more resource hungry on Mac than Windows It no longer seems an issue in version 6.
  2. It would be nice if it had Snippet support (like those of Sublime Text 2 - i.e. type 'fun' and tap 'tab' to put in a function. See @WickyNilliams comment below - With Live Templates you also have snippet support.
2
  • 10
    webstorm does have snippet support BTW ;-) though they're known as "Live Templates" instead of snippets. Sep 26, 2012 at 15:12
  • 3
    If you just want to debug a node.js app and already have an Intellij IDEA license you can just install the node.js plugin without having to buy the WebStorm license. Setting up a run/debug config is very easy once the plugin is installed. Jun 11, 2014 at 19:45
46

A lot of great answers here, but I'd like to add my view (based on how my approach evolved)

Debug Logs

Let's face it, we all love a good console.log('Uh oh, if you reached here, you better run.') and sometimes that works great, so if you're reticent to move too far away from it at least add some bling to your logs with Visionmedia's debug.

Interactive Debugging

As handy as console logging can be, to debug professionally you need to roll up your sleeves and get stuck in. Set breakpoints, step through your code, inspect scopes and variables to see what's causing that weird behaviour. As others have mentioned, node-inspector really is the bees-knees. It does everything you can do with the built-in debugger, but using that familiar Chrome DevTools interface. If, like me, you use Webstorm, then here is a handy guide to debugging from there.

Stack Traces

By default, we can't trace a series of operations across different cycles of the event loop (ticks). To get around this have a look at longjohn (but not in production!).

Memory Leaks

With Node.js we can have a server process expected to stay up for considerable time. What do you do if you think it has sprung some nasty leaks? Use heapdump and Chrome DevTools to compare some snapshots and see what's changing.


For some useful articles, check out

If you feel like watching a video(s) then

Whatever path you choose, just be sure you understand how you are debugging

enter image description here

It is a painful thing
To look at your own trouble and know
That you yourself and no one else has made it

Sophocles, Ajax

0
44

Theseus is a project by Adobe research which lets you debug your Node.js code in their Open Source editor Brackets. It has some interesting features like real-time code coverage, retroactive inspection, asynchronous call tree.

screenshot

2
  • this is pretty cool, still don't know what's Backtrace for tho
    – misaxi
    Feb 18, 2014 at 23:33
  • I'm currently loving Theseus, but I still have some problems where I need to set a breakpoint and trace through. I'm currently having to kill my app, start node with --debug, trace trhough and then start the app with node-theseus. Is it possible to use Theseus with breakpoints? I've tried searching around the GitHub page, StackOverflow and forums, but with no luck so far. Am I missing something?
    – Eugene
    Jul 15, 2015 at 1:21
27

Node.js Tools for Visual Studio 2012 or 2013 includes a debugger. The overview here states "Node.js Tools for Visual Studio includes complete support for debugging node apps.". Being new to Node.js, but having a background in .NET, I've found this add in to be a great way to debug Node.js applications.

0
25

Visual Studio Code has really nice Node.js debugging support. It is free, open source and cross-platform and runs on Linux, OS X and Windows.

You can even debug grunt and gulp tasks, should you need to...

2
  • 1
    Starting from Visual Studio Code 8.0 the debugging support for OSX and Linux got really good.
    – bgse
    Oct 20, 2015 at 2:35
  • After spending a whole evening getting node-inspector and strongloop to function under windows (Visual Studio Community, downgrade to npm 2, installing python, env variables, use cmd not babun / cygwin etc. etc.) and then playing with this for an hour, I have to say this is the best option at least in windows and possibly in general (if you don't have webstorn)
    – dashambles
    Feb 7, 2016 at 13:33
24

I wrote a different approach to debug Node.js code which is stable and is extremely simple. It is available at https://github.com/s-a/iron-node.

Enter image description here

An opensource cross-platform visual debugger.

Installation:

npm install iron-node -g;

Debug:

iron-node yourscript.js;

17

I created a neat little tool called pry.js that can help you out.

Put a simple statement somewhere in your code, run your script normally and node will halt the current thread giving you access to all your variables and functions. View/edit/delete them at will!

var pry = require('pryjs')

class FizzBuzz

  run: ->
    for i in [1..100]
      output = ''
      eval(pry.it) // magic
      output += "Fizz" if i % 3 is 0
      output += "Buzz" if i % 5 is 0
      console.log output || i

  bar: ->
    10

fizz = new FizzBuzz()
fizz.run()
0
16

If you are using the Atom IDE, you can install the node-debugger package.

16

Using Chrome Version 67.0.3396.62(+)

  1. Run node app

node --inspect-brk=0.0.0.0:9229 server.js(server js filename)

  1. Browse your app in chrome e.g. "localhost:port"
  2. Open DevTools.
  3. Click the the node icon beside the responsive device icon.

enter image description here

There will be another DevTools window that will pop out specifically for debugging node app.

enter image description here

13

There is built-in command line debugger client within Node.js. Cloud 9 IDE have also pretty nice (visual) debugger.

1
  • Cloud 9 is way to go for me, especially gives freedom of code anywhere option without carrying my laptop. Jan 8, 2016 at 15:40
11

I put together a short Node.js debugging primer on using the node-inspector for those who aren't sure where to get started.

10

Visual Studio Code will work for us in debugging.

9

Use Webstorm! It's perfect for debugging Node.js applications. It has a built-in debugger. Check out the docs here: https://www.jetbrains.com/help/webstorm/2016.1/running-and-debugging-node-js.html

8

If you need a powerful logging library for Node.js, Tracer https://github.com/baryon/tracer is a better choice.

It outputs log messages with a timestamp, file name, method name, line number, path or call stack, support color console, and support database, file, stream transport easily. I am the author.

0
8

Assuming you have node-inspector installed on your computer (if not, just type 'npm install -g node-inspector') you just have to run:

node-inspector & node --debug-brk scriptFileName.js

And paste the URI from the command line into a WebKit (Chrome / Safari) browser.

1
  • 1
    node-inspector was already mentioned; maybe delete this answer? Feb 12, 2014 at 1:46
8

Just for completeness:

The PyCharm 3.0 + Node.js Plugin offers an awesome development + run + debug experience.

8

Start your node process with --inspect flag.

node --inspect index.js

and then Open chrome://inspect in chrome. Click the "Open dedicated DevTools for Node" link or install this chrome extension for easily opening chrome DevTools.

For more info refer to this link

7

There is the new open-source Nodeclipse project (as a Eclipse plugin or Enide Studio):

Nodeclipse became #1 in Eclipse Top 10 NEW Plugins for 2013. It uses a modified V8 debugger (from Google Chrome Developer Tools for Java).

Nodeclipse is free open-source software released at the start of every month.

6

There are many possibilities...

Debug support is often implemented using the v8 Debugging Protocol or the newer Chrome Debugging Protocol.

5

IntelliJ works wonderfully for Node.js.

In addition, IntelliJ supports 'Code Assistance' well.

4

The NetBeans IDE has had Node.js support since version 8.1:

<...>

New Feature Highlights

Node.js Application Development

  • New Node.js project wizard
  • New Node.js Express wizard
  • Enhanced JavaScript Editor
  • New support for running Node.js applications
  • New support for debugging Node.js applications.

<...>

Additional references:

  1. NetBeans Wiki / NewAndNoteworthyNB81.
  2. Node.js Express App in NetBeans IDE, Geertjan-Oracle.
4

Use this commands

DEBUG_LEVEL=all node file.js
DEBUG=* node file.js
node file.js --inspect
4

ndb is an improved debugging experience for Node.js, enabled by Chrome DevTools

https://github.com/GoogleChromeLabs/ndb

3
node-debug -p 8888 scriptFileName.js

Not the answer you're looking for? Browse other questions tagged or ask your own question.