Node.js Tools for Visual Studio (NTVS) includes integrated support for debugging Node.js applications including, attaching to running Node.exe processes, evaluating Node.js (JavaScript) expressions in the watch and immediate windows, inspecting local variables, step in, out, and over statements, and breaking on exceptions.

This section provides a brief overview of debugging in Visual Studio, and details the extensions provided by NTVS.

Basic Debugging

To access full debugging support in NTVS, you will need to be using a project. (See Projects for information on creating and using projects.) With a project, you can associate debugging settings with your script, including a startup file and command-line arguments. These options will prevent you from needing to start your programs from the command line. See Debugging with a Project for information about modifying these settings.

When debugging Node.js applications with NTVS, principles common to all languages in Visual Studio apply.



Breakpoints, as shown in the image to the right, are lines of code where the debugger should stop executing and allow you to investigate the program state. They can be set by clicking in the margin of the code editor, or by right-clicking on a line of code and selecting Breakpoint, Insert Breakpoint.

If you want to set a breakpoint that only breaks under certain circumstances, you can set a condition. To do this, set the breakpoint, then right-click on the dot in the margin and select "Condition". In this dialog, you can provide an expression to evaluate each time the breakpoint is hit. If the expression is not true, or has not changed, the debugging will continue executing.

Conditional breakpoint

(Note that if the expression has side-effects then it may affect the behavior of your program.)

If you don't ever want to break at a breakpoint, you can convert it into a tracepoint. Right-click the dot in the margin and select "When Hit". The dialog will allow you to specify a message to be written to the Output Window, including values of any variable that would be accessible at that point.

Breakpoints can be cleared by clicking on the dot in the margin, or through the Breakpoints window (Debug, Windows, Breakpoints).


Stepping commands

Once you've broken into the debugger, you can step through your code one statement at a time. The step commands include Step Into, Step Over, and Step Out.

Step Into will execute the next statement and stop. If the next statement is a call to a function, the debugger will stop at the first line of the function being called. Check the Debug, Step Into menu to find the keyboard shortcut to use to step (typically F11).

Step Over will execute the next statement, but if it is a call to a function then the entire function will be executed. This allows you to easily skip functions when you are not interested in debugging them. Check the Debug, Step Over menu to find the keyboard shortcut (typically F10).

Step Out will execute until the end of the current function. It is useful when there is nothing else interesting in the current function. Check the Debug, Step Out menu to find the keyboard shortcut (typically Shift+F11).

If you want to continue running, you may use the Continue command (typically F5). Your program will not break until the next breakpoint. Note that when you Step Over or Step Out, if the running code hits a breakpoint it will break again, even if it has not reached the end of the function.

Inspecting values

While your program is broken in the debugger, you can view the contents of local and global variables using Quick Tips or the Watch windows.

To view a value using Quick Tips, simply hover the mouse over any variable in the editor.

Quick Tips

While debugging, you can also inspect variables using the Locals window and the Watch windows. The Locals window (Debug, Windows, Locals) contains all variables that are in the current scope.

Locals Window

The Watch windows (Debug, Windows, Watch, Watch 1-4) allow you to enter arbitrary Python expressions and view the results. These will be reevaluated for each step, and when breaking at a breakpoint.

Watch Window


If an error occurs while your program is being debugged, and you don't have an exception handler for it, the debugger will break and show you the error.

Exception popup

Now the debugger can be used to inspect the current state, including variables and the backtrace. If you continue or step, the exception will continue being thrown until it is either handled or your program exits.

If you are being interrupted often by the debugger breaking on exceptions, or if the debugger is not breaking on some exceptions that you would like it to break on, you can modify the settings in the Exceptions dialog. On the Debug menu, click Exceptions, and expand the Node.js Exceptions entry. Here you can see all the exceptions that are already know and can be configured.

Exceptions dialog

The left-hand checkbox ("Thrown") for each exception controls whether the debugger always breaks when it is raised. You should check this box when you want to break more often for a particular exception.

The right-hand checkbox ("User-unhandled") controls whether the debugger breaks whenever there is no catch statement in your code to handle the exception (or when the debugger fails to find a catch statement, which can happen if there is no source code available for a module). You should uncheck this box when you want to break less often for an exception.

To configure an exception that does not appear in this list, click the Add button to add it. The name must match the full name of the exception precisely.

Debugging with a Project

With a project, there are two options for starting debugging. The simplest is to press F5 (Debug, Start Debugging), which will launch your startup file (which is shown in bold in Solution Explorer).

Pressing Ctrl+F5 (Debug, Start without Debugging) will execute your sartup file without attaching the debugger. Often, programs will run faster without the debugger attached, and starting it with these commands will also use the project settings.

Command-line Arguments

To launch your script with certain command-line arguments, provide them as a Debug property.

Right-click on your project and choose Properties, then select the Debug tab. Here, you can provide the following options:

  • Node.exe path
  • Node.exe arguments
  • Script arguments
  • Working directory

The Search Paths setting matches what is shown in Solution Explorer. While you can modify this value here, it is simpler to use the other interface, which will allow you to browse for a folder.

Script Arguments are the most useful option. This text will be added to the command used to launch your script, appearing after your scripts name. The first item here will be available to your script as sys.argv[1], the second as sys.argv[2], and so on.

Interpreter Arguments are arguments for the interpreter itself, and appear before the name of your script. Common arguments here are -W ... to control warnings, -O to slightly optimize your program, and -u to use unbuffered IO. IronPython users can use this field to pass -X options, such as -X:Frames or -X:MTA.


Last edited Nov 21, 2013 at 6:38 PM by zacha, version 1


No comments yet.