Adapter not found or fails to start¶

Symptom: the window opens but nothing happens, or the session goes to failed immediately, or :DebugStart reports an error and stops.

What the log says¶

Open the Logs panel (Ctrl+L) and enable Session. One of these is usually there:

Log line resembles	Cause	Go to
the adapter's command was not found	not on `PATH`	1
the adapter started and died immediately	the adapter itself is failing	2
`program is not readable`	nothing to debug at that path	3
`launch` was refused with a message	the adapter objects to the request	4
no config and no language marker	there is no project	5
the build failed, with compiler output	the program does not compile	6

1. The adapter is not on `PATH`¶

By far the most common cause.

command -v codelldb
command -v dlv
command -v php-dbgp-adapter
python3 -m debugpy --version

If a check prints nothing, the adapter is not visible. Note that it may be visible to you and not to Bugsaur: a window launched from Neovim inherits Neovim's environment, which may differ from your shell's.

export PATH="$HOME/.local/share/nvim/mason/bin:$PATH"   # Mason
export PATH="$PWD/target/debug:$PATH"                   # php-dbgp-adapter

A more durable fix is to name the binary in the profile, avoiding PATH altogether:

[profiles.api]
adapter = "codelldb"
adapter_command = "${root}/vendor/codelldb"
program = "target/debug/api"

2. The adapter starts and dies¶

Enable the Adapter category in the log — it carries the adapter's own stderr, and the reason is usually stated there in the adapter's own words.

Frequent cases:

Adapter	Message	Fix
`debugpy`	`No module named debugpy`	install it into the interpreter named by `adapter_command`
`dlv`	a Go version mismatch	the built-in entry already passes `--check-go-version=false`; a custom catalog entry may not
`codelldb`	a missing shared library	reinstall CodeLLDB for this platform
`php-dbgp-adapter`	the port is in use	another project holds it — give this one its own `port`

3. `program` does not exist¶

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

Remember what program means per language: a compiled binary for Rust and C/C++, a package directory for Go, a script for Python, the project directory for PHP.

Bugsaur builds only for adapters whose catalog entry has a build — in practice Go. Rust and C/C++ you build yourself:

cargo build

4. `launch` is refused¶

The adapter received the request and objected. The message comes from the adapter and usually names the offending key.

This is where launch_arguments is worth checking: it is passed through unchanged, and a key replaces whatever Bugsaur generated rather than merging with it. A stray mode, program or cwd in there changes the launch completely.

Enable the DAP category to see the exact body that was sent.

5. No config and no language detected¶

The error names the directory it gave up in. It means the search reached the top of the tree without finding either .bugsaur/config.toml or a language marker.

The same message appears for a Python project that has a marker but no entry point with a recognised name — main.py, app.py, manage.py, __main__.py, src/<pkg>/__main__.py. The debugger will not invent one.

Write the config by hand; it is short. See Configuration → Profiles.

6. The build failed¶

The session goes to failed with the compiler's text and the adapter is never started — deliberately, since debugging a stale binary would be worse.

Fix the code, or run the build by hand to see the full output:

go build ./cmd/api
cargo build

Still stuck¶

Save the log (Save in the Logs panel writes the whole buffer regardless of filters) and check it against Reading logs.