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. In turn, 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 debugging information.
    
    • Bazel is one such build system. 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 methods 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 show_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