Skip to content

Troubleshooting: how to tell what broke

Debugging the debugger is a specific skill, and it is mostly about knowing which question to ask first. This page is the decision tree; the pages below it are the answers.

Start here

Find the first statement that is false for your session, and follow it.

1. The window opens
        ↓ no  → the binary or the adapter
2. The session starts and the program runs
        ↓ no  → the adapter or the profile
3. The program stops somewhere
        ↓ no  → the breakpoints
4. The stop shows the right source
        ↓ no  → the paths
5. The stop shows the right state
        ↓ no  → the build
Symptom Most likely Page
The window never appears bugsaur is not where you think, or the project has no config Adapter fails to start
The window opens, nothing happens the adapter did not start, or launch was refused Adapter fails to start
The program runs to completion the breakpoint never bound, or the code never ran Breakpoints not hit
It stops, but shows no source the debugger and the debuggee disagree about paths Source not found
It stops, but there are no variables optimised build, or a frame without debug info Breakpoints not hit
Neovim does nothing the plugin is not connected Neovim integration

The one tool that answers all of these

Whatever the symptom, the Logs panel — Ctrl+L — has the evidence.

  1. Turn on the Session category and read from the top. Phase changes, adapter start and death, and refused DAP requests all land there.
  2. If that is not enough, turn on Adapter — the adapter's own stderr, which is where language-specific complaints appear.
  3. Only then turn on DAP, the full request trace. It is noisy, but records are collected even while it is off, so you can enable it after the fact and still see what happened.

Details: Reading logs.

Three checks worth doing before anything else

They take under a minute and account for a large share of all failures.

Is the adapter visible to the debugger?

command -v codelldb    # or dlv, php-dbgp-adapter

PATH in the environment where Bugsaur runs is not necessarily the one in your shell — especially when the window is launched from Neovim.

Does program exist?

ls -l "$(pwd)/target/debug/my-binary"

For Rust and C/C++ it must be a compiled binary, and Bugsaur does not build it.

Which profile actually ran?

:DebugStart <name> picks explicitly; without a name, default from the config is used. Debugging the wrong profile looks exactly like a broken debugger.

When the answer is "it is supposed to do that"

Some surprises are designed behaviour. Before hunting further, check whether you have hit one of these:

Surprise Explanation
Breakpoints cannot be removed in the window the editor owns them — Breakpoints
A test run ignores saved breakpoints by design — Test under cursor
cwd and env do nothing for PHP the adapter launches nothing — PHP
Rust is not built for you only Go is — Rust
An unknown config key stops the launch the schema is closed — Configuration
gui_theme changes nothing the project's [ui] wins — UI