Reporting Complex VisualGDB Issues

Many VisualGDB issues happen in complex environments that include components from many different vendors. E.g. a typical STM32 project is built using a toolchain from ARM, HAL code from ST, and debugged by the community-maintained OpenOCD.

Using parts from different sources together can trigger glitches that would not be reproduceable on another machine. In order to successfully troubleshoot them, you would need to simplify the setup as much as possible:

  1. Try creating a new project of the same type from scratch.
  2. If the problem still persists, try removing and reinstalling BSPs, toolchains, SDKs and Python installations.
  3. If the problem only happens on a specific project, try comparing the 2 projects side-by-side:
    • Use a diffing tool (e.g. KDiff3) to compare the settings files, MSBuild files, CMake files, etc.
    • Try bringing the 2 projects closer together. E.g. remove additional files from the broken project, so both projects only contain 1 test file. This makes it easier to comare them.

The 3-step Format

If you can point out a specific setting that triggers the problem on a clean project, just let us know and we should be able to fix it timely. If we cannot reproduce it, we would ask you to provide a full description following the 3-step format below:

  1. What exactly you are trying to do (e.g. debug an imported STM32 project with OpenOCD after setting a breakpoint in main).
  2. What exactly you do expect to see (e.g. the breakpoint hitting immediately).
  3. Whe exactly do you actually see (e.g. "a frame not in module" message).

The description needs to include all the necessary steps for us to reproduce the same behavior on our side, starting from launching a new instance from Visual Studio. For simplicity, you can simply take screenshots of all the wizard pages and settings you change and paste them into a PDF file. Make sure you also include the relevant logs.

Below are a few examples of complete and incomplete problem descriptions.

Example #1: Insufficient Description

I renamed a file in my project and it doesn't build anymore.

If we tried following this on our side, we would create a new Linux project using the default "Hello World" template and would rename the main file. It would then build successfully.

Example #2: Complete Description

  1. Open VisualGDB Embedded Project Wizard
  2. Select "Create a new project -> Embedded Binary -> MSBuild"
  3. Select the ARM toolchain (GCC 9.2.0) and the STM32F407VG device.
  4. Select "STM32CubeMX Examples -> FatFS_USBDisk"
  5. Select ST-Link as the debug method
  6. Rename main.c to main.cpp
  7. Build the project
  8. Expected: successful build; got failed build, entire build log attached

From this description we would quickly that you are trying to clone a Plain C example from the ST SDK and build it as C++ without converting the code, and would point it out to you.

Example #3: 3rd-Party Components

I have imported the project and when I try to build it, it fails. Log attached.

Generally, we are not able to troubleshoot problems involving the code that is outside of our control. See the Custom Projects section below for hints on narrowing down those scenarios.

Example #4: Narrowed Down Problem

  1. I have imported the project (screenshots of wzard steps attached).
  2. When I build it manually, I have to set the "SDKROOT=<project directory>" environment variable and it works (successful build log attached).
  3. When I try to build it with VisualGDB, I didn't set this variable and it fails (build log attached).

We would then point out a tutorial, or a name of the setting in VisualGDB Project Properties that allows setting the SDKROOT variable similar to the manual build.

Custom Projects

Sometimes the issues only happen for large projects or solutions. Although we usually cannot review a specific project to check why it doesn't build, we still can help you if you follow the troubleshoting steps below:/p>

  1. Create a basic (e.g. "Hello, World" or "LEDBlink" project) with the similar configuration to your project.
  2. Check if the problem can be reproduced. If yes, simply share the setup details with us (e.g. Linux project based on CMake built with a Raspberry Pi cross-toolchain on another Linux machine).
  3. If the problem cannot be reproduced, try to make a list of the differences between the 2 projects and merge them in small batches (doing half at a time will help you pinpoint the cause very fast). E.g. if the debug session freezes, the steps would look like this:
    • Debug a "Hello, World" project with the same configuration.
    • Add the sources from the original project to it.
    • If the problem doesn't reoccur, compare the .vcxproj files of 2 projects and resolve the differences.
    • Compare the .vgdbsettings files of the 2 projects and resolve the differences (e.g. add custom debug steps).

Once you pinpoint a specific difference, let us know. In most of the cases, we are able to add workarounds, options to slightly modify the VisualGDB behavior, or checks for rare cases that will eliminate the problem.


For GUI-related problems please always include a screenshot of the entire window demonstrating the problem. Please do not crop it, as side windows like Solution Explorer often convey important information about your setup, e.g.:

Just one screenshot like this conveys that:

  1. It's a VC++-based project (rules out Advanced CMake, Arduino and Mbed).
  2. Using MSBuild (rules out GNU Make, QMake and basic CMake).
  3. Source structure is loaded (rules out IntelliSense backend communication issues).
  4. Using VisualGDB 5.4 (rules out bugs present in older releases).
  5. Automatic code completion is enabled (changes the order of some internal events).
  6. IntelliSense results are filtered (helps pinpoint inaccuracy issues).
  7. The project is under source control (enables extra checks on the VisualGDB side that may be related).

Diagnostic Logs

VisualGDB provides several ways to make pinpointing problems easier. We recommend checking them before submitting a bugreport and including the relevant parts:

  • View->Other Windows->VisualGDB Diagnostics Console. This window shows detailed logs on all low-level VisualGDB activity. E.g. launched Linux commands, copied files, internal exception traces. If you suspect the problem is related to some external tools, please check this window first.
  • View->Clang IntelliSense Status. This window shows detailed logs from the Clang IntelliSense engine and also the project status as seen by the engine (i.e. the exact list of source files and their flags). It can be helpful in understanding why the IntelliSense cache is being rebuilt too often, why a source file parsing is too slow, or why some IntelliSense suggestions are missing.
  • VisualGDB Project Properties -> Advanced GDB Settings -> Save low-level interaction with GDB. This option will save all lines sent to an received from GDB (with timestamps) int oa log file. It is useful in understanding the inaccurate variable values or stack traces, breakpoints issues and strange GDB crashes.

External Tools

If an error happens in an external tool launched by VisualGDB, you can usually view the output from the tool, that should include the error details by expanding the detail view as shown below:


For your convenience, the tool output will also be copied to the VisualGDB Diagnostics Console.

Internal Errors

When VisualGDB reports an internal error or an exception, it allows viewing the stack trace of the exception by clicking the "Show exception details link":


If you are reporting an exception, make sure you include the exception trace (including the VisualGDB build number shown in the trace).

GDB Errors

If a debug session fails to initialize, or ends unexpectedly, VisualGDB shows detailed logs from all involved components (typically, gdb and OpenOCD or other debug stub). Make sure you check all of those logs and include them with your error report: