Breakpoints are not getting hit

Symptom: The 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.

Many compilers default to not emitting the debugging information and need to be explicitly instructed to do this.

The path of the file you are setting a breakpoint in does not match path stored in module's debugging information.

Some reasons for why this might happen (this list is not exhaustive):

• 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.
• 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.
  • If debugging a Rust program, check whether the source path contained symlinks: rustc replaces symlinks with their targets when emitting debug info.

How to investigate:

• In a debugging session:
  • Use debug_info list command to list modules in the current debuggee, which have line-level debugging information.
  • Use debug_info show <module name> command to get a list of all source files (aka compilation units) present in the debugging information.
• Outside of a debugging session:
  • In VSCode Command Palette, find and execute "LLDB: Command Prompt" command.
  • Use debug_info show --file <module path> command at the prompt.

If you don't see your source file(s) in the list, the most likely culprit is the reason #1 above. You can further investigate using these instructions.
Otherwise, compare outputted path prefix of the source files to their actual location. This will give you an idea of what needs to be entered into the path mapping.

Hot to correct:

Missing debug info

If you've narrowed the problem to missing debug info, please make sure that your compiler (and possibly linker) are configured to emit debugging information. Most C++ compilers, as well as the Rust compiler, use the -g flag for this purpose.

Source file path mismatch

The recommended way: add "sourceMap": { "<source tree path at compilation time>": "<source tree path during debugging>" } to your launch configuration. The latter path is usually ${workspaceFolder}. These mappings must be bijective (i.e. one-to-one), as the debugger needs to be able to translate paths in both directions.

The quick way: add "breakpointMode": "file" into the launch configuration. This will cause breakpoint resolution to be done using file name only (like the breakpoint set -f <file> -l <line> command would). Note, however, that this may have undesirable effects, as the breakpoints will be set in all files of the same name in the project. For example, Rust projects often contain lots of files named "mod.rs".

---

See also: LLDB troubleshooting