Neovim integration issues¶

Symptom: commands are missing, nothing happens when you run them, or the editor and the debugger disagree about the state.

`:DebugStart` is not a command¶

setup() never ran. Check the path in dir (lazy.nvim) or in rtp:prepend, and that it points at the repository root — the one containing lua/bugsaur/.

After fixing your config, restart Neovim or :source $MYVIMRC and call setup again.

The command runs but nothing happens¶

Check, in this order:

1. The error the plugin recorded

:lua print(vim.inspect(require("bugsaur").state.last_error))

2. The socket

ls -l /tmp/rust-debugger-nvim-*.sock

3. The binary

:lua print(require("bugsaur").state.binary)

It must be an existing executable. binary in setup() should be an absolute path to the built debugger — that is what makes a globally installed bugsaur unnecessary.

The adapter is not found, but only from Neovim¶

A window launched by Neovim inherits Neovim's environment, not your shell's. An adapter that command -v finds in your terminal can still be invisible to the debugger.

Either export PATH where Neovim will see it, or avoid PATH entirely by naming the binary in the profile:

adapter_command = "${root}/vendor/codelldb"

`:DebugTest` refuses to start¶

Three rules, and all three are deliberate:

The cursor must be inside a test function. In Rust the #[test] line counts. On a test group line — mod tests — the whole group runs.
The buffer must be saved. The backend reads the file from disk.
Saved breakpoints are not used. Only the breakpoints of this request are.

Window options seem to be ignored¶

Three of the four are read when the GUI process starts: gui_focus_on_stop, gui_theme, gui_layout. Editing init.lua and re-sourcing does nothing to an already open window — close it and start a new session.

auto_attach is different: it is read on every setup() call.

And gui_theme / gui_layout apply only when the project said nothing. A [ui] section in .bugsaur/config.toml always wins, because it is shared by everyone opening that project. See Configuration → UI.

Keys work in the editor but not in the window¶

They are two separate binding systems, and this is expected. Neovim mappings cannot reach the debugger window, which is a separate process with its own keyboard handling.

Window bindings come from gui_keymaps in setup(), and the project can override them per action through [ui.keymaps]. Press F1 in the window to see what is actually in effect. Full explanation: Keymaps.

Breakpoints disagree between editor and debugger¶

A file changed outside the editor. Line numbers are stored literally, so a rebase or a formatter run while Neovim was closed leaves breakpoints on their old line numbers.

The file is outside any project. A file not under a .bugsaur/ root has nowhere to be saved; its breakpoints live until the editor session ends.

An explicit --break was used. It replaces the saved set entirely rather than adding to it.

See Breakpoint synchronization.

The session survived, the editor did not¶

That is the design, not a bug. Closing Neovim does not end the session — the backend keeps running, and reconnecting gets the current state.

To reattach automatically on the next start:

require("bugsaur").setup({ auto_attach = true })

The window is hidden behind the browser¶

Common with PHP, where the stop is triggered by a request from outside the editor. Either raise it manually with :DebugFocus, or have it raise itself:

require("bugsaur").setup({ gui_focus_on_stop = true })