skip to content

Under rust-lldb, how do you stop a Rust program at the moment it panics, and then reach the frame that caused it?

level: middleimportance: should knowfreq 30%

answer

  1. std names a function for this
  2. after the hook, before unwinding
  3. LLDB exception breakpoints won't help
  4. bt, then frame select

basics

~20 s

Set breakpoint set -n rust_panic: std keeps that function as the place to break, after the panic hook runs but before unwinding starts. Then bt, frame select the first frame in your crate, and frame variable.

solid answer

~40 s

std's `panicking.rs` keeps a function named `rust_panic`, `#[inline(never)]` and with a fixed symbol name, documented as the place "on which to slap yer breakpoints". `breakpoint set -n rust_panic` resolves to `__rustc::rust_panic`. Every panic reaches it after the panic hook has run (for a binary run directly, the message is already on stderr) and before the panic runtime starts unwinding, so every frame is still there. It is hit under `-C panic=abort` too. LLDB's language exception breakpoints do not help: `breakpoint set -E rust` is rejected as unsupported. Once stopped, `bt` shows std and core frames marked `[opt]` on top, then the generic `Index` impls instantiated in your crate, then your function. `frame select N` on that frame and `frame variable` show the locals that caused it.

code

rust · 12 lines
rust
use std::collections::HashMap;

fn latency(hits: &HashMap<String, Vec<u32>>, route: &str) -> u32 {
    let samples = &hits[route];
    samples[3]
}

fn main() {
    let mut hits: HashMap<String, Vec<u32>> = HashMap::new();
    hits.insert("GET /".to_string(), vec![12, 9, 15]);
    println!("{}", latency(&hits, "GET /"));
}

go deeper

for a junior

Know that you can stop on a panic with a breakpoint on rust_panic and then look at the call stack with bt.

for a middle

Explain the order inside std: the hook prints the message, then rust_panic, then the panic runtime unwinds or aborts, which is why frames are still intact at the stop.

for a senior

Show the walk: skip the [opt] std frames, use generic Index frames for arguments, frame select your own frame, and know why LLDB exception breakpoints do not apply.

for a principal

Mention when a debugger stop beats logs and backtraces, such as a panic that depends on state no log captured, and when it does not, such as production.

## Where std gives you a breakpoint The standard library keeps one function for exactly this job. In `library/std/src/panicking.rs`, `rust_panic` is marked `#[inline(never)]` and carries the comment "A function with a fixed suffix (through `rustc_std_internal_symbol`) on which to slap yer breakpoints." Because it is never inlined and its symbol name is stable, `breakpoint set -n rust_panic` resolves in a binary built against std. In LLDB the location shows up as `__rustc::rust_panic` in `panicking.rs`. ## What has happened by the time it stops Every panic takes the same path through std: 1. Your code panics. An out-of-bounds index, for example, calls `core::panicking::panic_bounds_check`, which calls `core::panicking::panic_fmt`. 2. Control enters std's panic handler (`__rustc::rust_begin_unwind` in the backtrace), which leads to `std::panicking::panic_with_hook`. 3. `panic_with_hook` runs the **panic hook**. The default hook prints `thread 'main' (...) panicked at src/main.rs:5:12:` and the message. 4. `panic_with_hook` calls `rust_panic`, which calls `__rust_start_panic` to hand the payload to the panic runtime, which then unwinds or aborts. A breakpoint on `rust_panic` therefore stops **after** the hook has run (for a binary run directly, the message is already on stderr) and **before** any frame is unwound or any destructor runs. The process is still alive, every frame is intact, and the locals that caused the panic can still be read. The same breakpoint is hit when the binary is built with `-C panic=abort`, because the abort happens inside `__rust_start_panic`. ## Why the other obvious routes fall short | Approach | What happens | |---|---| | `breakpoint set -E rust` | `error: invalid value ('rust') for -E (language-exception): Unsupported language type for exception breakpoint` | | A breakpoint on `abort` | An ordinary unwinding panic in `main` does not call it; the process just exits with status 101 | | `RUST_BACKTRACE=1` without a debugger | Prints the call stack, but the process is gone and no variable can be read (backtraces are covered with error context) | | A breakpoint on your own line | Works only once you already know which line panics | ## Walking from the panic to the cause After the stop, `bt` lists the frames from the top. In a session on a program that indexes `samples[3]` in a three-element `Vec`: - Frames 0 to 6 are std and core: `rust_panic`, `panic_with_hook`, the handler closure, `rust_begin_unwind`, `panic_fmt`, `panic_bounds_check`. They are marked **`[opt]`** because the standard library ships precompiled with optimisation. - Frames 7 to 9 are generic indexing code (`<[u32] as Index<usize>>::index`, `<Vec<u32> as Index<usize>>::index`). Generic code is compiled into your crate, so these frames show arguments: `self=size=3, index=3`. - Frame 10 is your code: `pan::latency(hits=size=1, route="GET /") at pan.rs:5:12`. `frame select 10` moves there and `frame variable` prints the locals, with the Rust formatters showing `hits` and `route` readably. In the `[opt]` std frames, `frame variable` answers `error: no variable information is available in debug info for this compile unit`. The precompiled standard library has line information (each frame shows `panicking.rs:80:14` and similar) but no variable information for its own non-generic functions. ## Panics inside a unit test A failing `#[test]` is debugged the same way, against the test executable rather than through `cargo test`: 1. `cargo test --no-run` builds the tests and prints the executable, for example `Executable unittests src/lib.rs (target/debug/deps/tlib-4c7b1d9d7e820986)`. 2. Start it as `rust-lldb -- <test executable> <test name>`, so the harness runs only that test. 3. `breakpoint set -n rust_panic`, then `run`. The stop lands on a thread named after the test (`thread #2, name = 'tests::p95_of_three'`), because the harness runs each test on its own thread, and `bt` leads to `tlib::p95(samples=size=3) at lib.rs:4:6`. One difference from a plain binary: the harness captures the test's output, so the panic message is not on the terminal at the stop; it is printed later, with the test's failure report. ## Practical notes - A panic on a spawned thread hits the breakpoint on that thread. `thread list` shows the others, and `bt` works on the one that panicked. - `continue` after the stop lets the panic proceed normally: unwinding, destructors, then the exit status or the `JoinHandle` result. - The breakpoint only stops; what a panic means for the program (when to panic, hooks, `catch_unwind`) is the panics material in the language tree.

  • Does a `rust_panic` breakpoint still fire when the binary is built with `-C panic=abort`?
    Yes. With the abort strategy, std still prints the message through the hook and calls `rust_panic`; it is the panic runtime behind `__rust_start_panic` that aborts instead of unwinding. A session on such a binary stops at `__rustc::rust_panic` exactly as an unwinding build does, with the same frames below it.
  • Why do the top frames show no locals while your own frame does?
    Those frames are std and core functions from the precompiled standard library, built with optimisation. It carries line information, so LLDB shows `panicking.rs:840:5`, but no variable information, so `frame variable` reports none for that compile unit. Your crate's debug build, and generic std code instantiated in it, carry full variable information.

  • `breakpoint set -E rust` stops on Rust panics the way C++ exception breakpoints work.
  • By the time a debugger can stop, the panic has already unwound the stack.
  • A breakpoint on abort catches every Rust panic.
  • RUST_BACKTRACE=1 gives the same information as stopping in a debugger.
  • The std frames lack variables because the build forgot -g.