Attach to a running process¶

Debug a process that is already running, instead of launching one.

Use this when the interesting state exists only after a long startup, when the process is a server you do not want to restart, or when the bug appears only under real traffic.

The profile¶

[profiles.attach]
adapter = "codelldb"
program = "target/debug/app"
mode = "attach"

[profiles.attach.launch_arguments]
pid = 4242

mode = "attach" at the profile level is DAP's mode. program is still needed — the adapter uses it to find debug information — but nothing is launched from it.

Find the pid:

pgrep -f my-app
ps aux | grep my-app

Nothing is built¶

Attach mode skips Bugsaur's build step entirely, and deliberately: the process is already running, and rebuilding would produce a binary that no longer matches what is executing in memory.

Make sure the binary in program is the same build as the running process. Debug information from a different build gives wrong line numbers and wrong variables — a failure mode that looks like a debugger bug.

A pid that changes every time¶

Hard-coding a pid in a committed config is not practical. Two ways around it:

Name it at launch, through the manual mode:

bugsaur gui --adapter codelldb --program target/debug/app \
  --launch-arguments "{\"pid\": $(pgrep -f my-app)}"

Or attach by name, if your adapter supports it — CodeLLDB does:

[profiles.attach.launch_arguments]
program = "my-app"
waitFor = true

waitFor makes the adapter wait for the next process with that name to start, which is the practical way to debug something during its startup.

Per adapter¶

Adapter	How to attach
CodeLLDB	`pid`, or `program` with `waitFor`
Delve	`mode = "attach"` in `launch_arguments` plus `processId`
debugpy	`connect` to a `debugpy.listen()` endpoint in the process
PHP	always effectively attach — the adapter listens, Xdebug connects

The exact keys belong to the adapter, and Bugsaur passes launch_arguments through unchanged. Check the adapter's own documentation.

PHP does not need this page

The PHP adapter never launches anything, so every PHP session is already an attach in spirit. See Languages → PHP.

Detaching¶

Stopping the session — Cmd+F2 or :DebugStop — ends the debug session. Whether the attached process is left running or terminated depends on the adapter's policy; for a server you did not launch, expect it to keep running.

When it does not work¶

Symptom	Cause	Fix
Permission denied	the OS forbids attaching to another process	run with elevated permissions; on Linux check `ptrace_scope`
Attached but no symbols	`program` is a different build	point at the binary the process was started from
Wrong lines, wrong variables	same cause	as above
The pid is gone	the process restarted	use `waitFor`, or find the new pid