Skip to content

Debugging an application

VS Code comes with a built-in debugger to help troubleshoot problems. If you forgot to enable debugging during the build configuration step, add the following lines into the application configuration file prj.conf and then run a Pristine build by clicking on the icon to the right of Build from the Actions panel.


The are two options listed in the Actions panel for debugging with the extension:

  • Debug, which uses GDB.
  • Debug with Ozone for J-Link.


Ubuntu users with nRF Connect SDK 1.7.0 need to install the libcurses5 package for debugging to work properly. Run the following command:

sudo apt install libncurses5

To use debugging with GDB:

  1. Click on Debug in the Actions panel.
  2. The debugging control bar appears at the top of the screen to let you control the debugging process.

    Control Description
    Start/Continue Starts or continues the debugging process
    Step over Steps over a function
    Step in Steps into a function
    Step out Steps out of a function
    Restart Restarts the debugging process
    Stop Stops the debugging process
  3. Click on the left side of any line of code to set or remove a breaking point.

See the the VS Code debugging documentation for additional information.

Debugging panels

There are several debugging panels available to help you examine the debugging process.


The Variables panel shows variables in the current scope and organizes them into local, global, and static sections.

Debugging variables


The Watch panel shows the output of variables you have selected to watch.

To start watching a variable:

  1. Click and drag the mouse cursor to highlight the variable in your code.
  2. Right-click and choose Add to Watch.
  3. Click the Start/Continue button in the debugging control bar to watch the debugger go through the code until it stops at a variable breakpoint. The output of the code displays in the Watch panel.

Debugging watch

Call stack

The call stack lists all of the available threads and indicates which ones are running. It also includes the call stack for each individual thread that is running.

Debugging call stack


All breakpoints that you have set in the code are listed in the Breakpoints panel.

Debugging breakpoints

Cortex peripherals

The Cortex Peripherals panel shows a memory map of peripherals on the device. You can open and expand the registers and can write or read to them depending on permissions.

Debugging cortex peripherals

Cortex Registers

This panel gives you full access to a list of available CPU registers.

Debugging cortex registers

Debug troubleshooting

There is a known issue where debugging may not work when you enable debug options when generating the build configuration. This seems to happen with simple sample applications, such as Blinky. Samples that use threads still seem to work with Enable debug options checked.

To work around this issue, generate the build configuration with Enable debug options unchecked. If this does not resolve the issue, start debugging by using Run -> Start Debugging or pressing F5 instead of starting by clicking the Debug Application icon.

When attempting to debug a device that has readback protection enabled, the debugger may time out with no explanation. The solution is to recover the device, either by running the nRF Connect: Recover Board command or by clicking the Recover icon in the Connected Devices panel. Once the device has been reset, restart the debugger.

Back to top