Breakpoints are not getting hit

Symptom: Debugger does not stop on breakpoints / breakpoints are grayed out.

This usually means one of the two things:

• The debugger cannot locate debugging information for the module you are setting a breakpoint in.
  Please make sure that you are compiling with debug information emission enabled. Most C++ compilers, as well as the Rust compiler, use -g flag for this purpose. You can check whether your binary has debug info by following these instructions.
• The path of the file you are setting a breakpoint in does not match path stored in module's debugging information. This may happen because:
  • You are debugging on a different machine than the program was compiled on. This includes compiling or debugging in a Docker container if the source tree is not mounted at exactly the same location. To correct this, add "sourceMap": { "<source tree path at compilation time>": "<source tree path during debugging>" } to your launch configuration. The latter path is usually ${workspaceFolder}.
  • Your build system or compiler rewrites source tree location embedded in the debug info:
    
    • In order to achieve repeatable builds, Bazel, makes source file paths relative to the current directory. To fix, add "sourceMap": { "/proc/self/cwd": "<source tree path> } to your launch configuration on Linux, or "sourceMap": { ".": "<source tree path>" } on MacOS or Windows.
    • If debugging a Rust program, check whether the source path contained symlinks: rustc replaces symlinks with their targets when emitting debug info. To fix, add "sourceMap": {"<original path>: "<symlinked path>"}.

Diagnosing

In order to to investigate these issues you will need to pause your program at a point where all relevant modules have already been loaded:

• Try creating a breakpoint by file name only (usually breakpoints are created using the full file path): "preRunCommands": ["breakpoint set -f <file name> -l <line number>"].
• Try creating a function breakpoint or a regex function breakpoint.

If either of these succeeds (i.e. the program stops at one of these breakpoints), use breakpoint list --verbose to see where LLDB has managed to find this file or function. Note that your program may contain more than one file or a function with the same name, including those originating from third party code. Another useful command is debug_info which will dump source paths of all compilation units in the currently loaded modules.

If you are having trouble stopping at any breakpoints, try forcing a stop at the program entry point by adding "stopOnEntry": true to your launch configuration. This method has the disadvantage of not being able to see modules dynamically loaded later in the program execution.

Finally, you may also try interrupting your program by pressing the pause button (⏸️) or issuing process interrupt command.

See also: LLDB troubleshooting