PanicGraph

Reports which functions in a Rust crate can panic, why, and through what call path. It reads the compiler's own view of the program, so the answer covers the code you wrote and everything it calls, down into the standard library.

The problem with asking that question honestly is that the answer is "nearly everything": every Vec::push can fail to allocate, so every function that touches a growable collection is a panicking function. panicgraph's central idea is that you can assume a category of panic impossible and have the whole analysis re-run under that assumption, rather than filtering it out of a finished report.

Requirements

The analysis is a compiler driver, so it needs a nightly toolchain and the compiler's own libraries:

rustup toolchain install nightly
rustup component add rustc-dev llvm-tools --toolchain nightly

The +nightly in the install line below selects that toolchain, and a rust-toolchain.toml does the same if you build from a checkout instead. The build stops with an explanation rather than a linker error when either piece is missing.

Install

cargo +nightly install panicgraph

That installs two binaries, panicgraph and panicgraph-driver. They live next to each other and both are needed.

To work on panicgraph itself, build from a checkout instead, where rust-toolchain.toml selects the toolchain for you:

cargo install --path .

A smaller build for continuous integration

The interactive view and the drawing exist for a person looking at a result. A build that only needs a verdict can leave them out:

# report and check only
cargo install panicgraph --version VERSION --no-default-features

# keep the drawing, or keep the view
cargo install panicgraph --version VERSION --no-default-features -F svg
cargo install panicgraph --version VERSION --no-default-features -F serve

VERSION stands for the release you want, which cargo search panicgraph prints and panicgraph -v reports for a machine that already has one, as does --version; the first line of panicgraph --help names it as well. Use --path . in place of panicgraph --version VERSION to build the same thing from a checkout.

Dropping both removes the compression dependency and the scripts the view is built from, which is most of a megabyte of binary. -l and --format svg are then rejected as unknown arguments rather than silently doing nothing.

Getting started

Run it in a crate:

$ panicgraph
Analysis
    rustc              1.100.0-nightly (f7d782a3b 2026-08-19)
    profile            release (debug assertions off, overflow checks off)
    standard library   shipped
    suppressed         capacity-overflow, alloc-failure, ub-check
    functions          56 analysed, 10 can panic

divz
    defined at src/lib.rs:5:1
    divide-by-zero attempt to divide by zero at src/lib.rs:5:38

expect_res
    defined at src/lib.rs:3:1
    unwrap reached through a call

The header is part of the answer. Overflow checks do not exist in a build that has them turned off, so a report that does not name its profile is not saying anything definite. Cargo features decide which code exists at all, so --features, --all-features and --no-default-features are passed through to the build, and a selection other than the default is named in the header and recorded by a baseline.

Assuming panics impossible

By default, allocation failure, capacity overflow, and standard library precondition checks are assumed impossible. Turn that off and the picture changes:

$ panicgraph --suppress ''
    suppressed         nothing
    functions          56 analysed, 12 can panic

push_vec
    defined at src/lib.rs:7:1
    capacity-overflow reached through a call

push_vec is a one line wrapper around Vec::push. With the default policy it does not appear at all, because the only panic it reaches is one you asked to assume away.

This is not a display filter. The assumption is applied before the analysis propagates, so a function that panics only through a suppressed category is genuinely clean, and so is everything above it. It also reaches into control flow: a Drop that runs only while an allocation failure unwinds becomes unreachable along with the failure itself.

Select categories by name or by group:

panicgraph --suppress foreign           # calls into C
panicgraph --suppress oom               # allocation only
panicgraph --suppress ''                # assume nothing
panicgraph --suppress all               # assume everything, which reports nothing
panicgraph --only unwrap,index          # report just these
panicgraph kinds                        # list the categories

Generic functions

A generic function is analysed as written, with its parameters left open, so a check on a const parameter or on the size of a type parameter is reported, and a call through a bound reports generic-bound. That is the honest answer for the function. For the answer about the uses the build makes of it:

panicgraph --generics instantiated

reports each generic function through the instantiations the build makes, and falls back to the body as written only where nothing instantiates it. A library's own code rarely instantiates its public interface, so

panicgraph --with-tests --generics instantiated

builds the crate's test targets as well and reads the instantiations they make. The tests themselves are not reported, and neither is the crate's code compiled again for its unit tests.

Explaining one function

$ panicgraph why unwrap_opt
unwrap_opt can panic with `unwrap`:

  unwrap_opt
      calls std::option::unwrap_failed at .../core/src/option.rs:1014:21

For a deeper path this prints each call in turn, marking the ones that run only while an earlier panic is unwinding. When a name covers several bodies, such as a generic function and its instantiations, or a function and its closures under --closures parent, each panic is explained through a body that reaches it.

A finding every call reaches is marked (always) in the report, and always in the machine readable one: no path through the function returns without raising there, no loop can spin instead, and the check, where it is one, fails every time. It is the difference between a stub that is not written yet and a check some argument can fail.

Gating a build

check fails when a function that must not panic can. With no gate named, no function in the crate may panic, which is the question an allocation free or embedded crate asks:

$ panicgraph check --forbid '^(idx|divz)$'
2 functions must not panic and can:

divz
    at src/lib.rs:5:1
    divide-by-zero (must not panic)
idx
    at src/lib.rs:1:1
    index (must not panic)

Run `panicgraph why <function>` to see how one of them gets there.
$ echo $?
1

Patterns are regular expressions and may be repeated. --allow carves known exceptions out of a broad rule, so the rule can stay broad:

panicgraph check --forbid '^api::' --allow '^api::legacy_'

Other gates. Naming any of them replaces the default rule rather than stacking with it, so a ceiling means a ceiling:

panicgraph check --max 20               # fail above a ceiling
panicgraph check --fail-on-unknown      # refuse panics the analysis could not classify

Ratcheting an existing crate

Most crates cannot go to zero today. Record what panics now, then fail only on what is new:

panicgraph baseline panicgraph.json
panicgraph check --baseline panicgraph.json

A function absent from the record fails. So does one already recorded that has gained a panic it did not have before, which a record of names alone would miss. Functions are recorded under their crate, so two crates of a workspace can each have a main without one standing in for the other. Functions that stop panicking are reported so the file can be refreshed rather than drifting.

In a workflow

- uses: dtolnay/rust-toolchain@master
  with:
    toolchain: nightly-DATE
    components: rustc-dev, llvm-tools
- run: cargo install panicgraph --version VERSION --locked
- run: panicgraph check --baseline panicgraph.json --format github

VERSION and DATE are placeholders for values you write into the file: a released version of this tool, and a nightly spelled nightly-YYYY-MM-DD.

Pin the version. A release can change what the analysis reads, so a function no earlier version could explain may be reported by the next one, and a check that passed yesterday fails today on code nobody touched. Naming VERSION keeps a red build about the commit that caused it, and --locked does the same for the tool's own dependencies.

Pin the toolchain for the same reason. The analysis reads MIR, so a newer nightly changes which checks exist before panicgraph ever sees them, and the driver links compiler internals that have no stable interface, so a floating nightly can stop building altogether.

Upgrade either one deliberately, and write the record again in the same commit with panicgraph baseline panicgraph.json, so the baseline and the tool that reads it move together.

--mir-opt-level 3 builds the analysis at the compiler's next MIR optimization level, where the compiler's own dataflow constant propagation settles more checks before the analysis reads a body. The artifact then differs from a plain build, so the report names the level, and a baseline records it.

--format github writes workflow commands, so a failure lands on the line of the function it is about instead of at the bottom of a log:

::error file=src/lib.rs,line=16,col=1,title=Function can panic::newly_added can panic with index (not in the baseline)

Exit codes are 0 for nothing to report, 1 for findings or a failed check, and 2 when the tool could not complete.

Looking at it

panicgraph -l 8080

Serves an interactive flame graph: assume categories impossible and watch what survives, lock the view to a single category, search frames with ctrl f and step through the matches, click a frame for the call path. A bare port binds the loopback interface only; opening it more widely has to be asked for with -l 0.0.0.0:8080, because it serves the source of the crate being analysed.

For something to attach to a report, write a standalone flame graph instead:

panicgraph --svg > panics.svg
panicgraph --svg --dark > panics.svg

The file carries its own styling and behaviour, so it opens from disk with nothing else present, and every frame keeps a title so it still explains itself when scripting is off. It is as wide as the window it is opened in: the frames stretch, the text keeps its size, and the labels are fitted again whenever the window changes, so a wide screen shows more names. With scripting off it is the 1200 pixel drawing flame graph tools have always made, scaled as a whole to fit. The mark in the corner links to the project and names the version that drew the file, for a reader handed the picture alone.

--svg is short for --format svg. --dark draws the file in the dark colours of the interactive view, which --theme light and --theme dark name in full. Every policy flag applies to the drawing as it does to the report: --only narrows it to the categories named, --all-crates draws dependencies too, --closures parent folds closures into the functions they are written in, --generics instantiated draws what the build's own instantiations do, --static-only leaves out calls through objects and pointers, --candidates follows their candidate targets, and --verify writes the artifact's verdict on each panic. What the drawing was narrowed or widened to is written under its title.

Frames are coloured as in the interactive view: three hue families say what kind of panic a frame is, each category takes a step of its own on its family's hue, and a call is tinted by the family most of the panics under it belong to. Both read assets/palette.json, so a category is the same colour in the file and in the view, and changing a colour there changes it in both.

Clicking a frame zooms into it: the path it sits on stays in view as full width bars and everything the frame does not contain goes, so what is left is a picture of one path. ctrl-F searches the frames with a regular expression, colours what matched, and says what share of the whole those matches account for. Reset Zoom and Reset Search undo either. A search is written into the address, so a picture opened at a finding can be handed on as it stands. The policy the graph was drawn under is written under the title, because a flame graph of what can panic says nothing definite without the assumptions behind it.

Machine readable output is available everywhere with --json, short for --format json.

Checking findings against the compiled artifact

This is a may-panic analysis over MIR, and the optimizer sees further than the folder does. --verify disassembles the libraries the analysis build produced and follows each finding into the machine code:

verify_absent_loop
    index reached through a call (absent from the compiled artifact)
must_index
    index index out of bounds at src/lib.rs:10:5 (confirmed in the compiled artifact)

A confirmed finding still calls a panic entry point in the artifact. An absent one was removed by the optimizer: every call the compiled function makes was accounted for and none reaches a panic. Everything else is unverified, which includes calls through registers, code the sweep cannot see into, and categories that leave no symbol behind, such as a reference count overflow's inlined trap. The verdict annotates the finding and never removes it: absence from one artifact is a fact about that build, not a proof about the source.

The sweep is also read the other way round. A function the analysis reports clean whose compiled code still reaches a panic entry point is listed after the findings, so a check the analysis settled that the optimizer kept is in view rather than hidden behind the proof. It is worth a look rather than a verdict: the artifact reads a function with its callees folded in, so a check a callee keeps for other callers counts against it, a caught panic still names its entry point, and a check the optimizer could not settle is kept whether or not it can fail. A function reported with a category that names unread code is left out, since that admits anything already.

The standard library itself

The library sources ship with the toolchain, as the rust-src component the analysis already needs, and each of its crates can be analysed as the crate under analysis:

S=$(rustc +nightly --print sysroot)
cp -r "$S/lib/rustlib/src/rust/library" ./std-src
rm std-src/.cargo/config.toml
panicgraph --manifest-dir std-src -p core
panicgraph --manifest-dir std-src -p alloc
panicgraph --manifest-dir std-src -p std --features panic-unwind

The copy keeps the analysis build out of the toolchain's tree, and its .cargo/config.toml goes because it points at a vendor directory the component does not ship. The workspace is recognised as the library's own by the shim crate it patches in, and every crate in it is compiled the way the library's build compiles them, with whatever carries no stability forced unstable; that is what lets the stable parts of std lean on the crates vendored under them. Neither RUSTC_BOOTSTRAP nor any RUSTFLAGS is needed: the tool runs on nightly, where the library's unstable features are allowed, and it passes the flag the library's own build passes. std is built with its panic runtime as a dependency, behind the panic-unwind feature: without it the compiler injects the toolchain's own runtime, whose core then clashes with the one being built.

Measuring precision over a corpus

scripts/corpus.sh runs the analysis over a list of crate directories and prints one markdown table row per crate: functions analysed, findings, how many findings carry only assumed categories, how many distinct definition sites the rest come from, and the busiest categories. Running it over crates whose panic freedom is proven externally turns every non-assumed finding into a false positive to investigate, and keeping the table in a log makes precision drift visible between toolchains and releases. The column of distinct sites is the one to watch on a crate that stamps out one function per array size or integer type with a macro, where a single check counts once there and many times among the findings.

How it works

The analysis runs as a compiler driver invoked through RUSTC_WRAPPER, over monomorphized MIR. Panic reasons come from the compiler's own Assert terminators and from calls to panic entry points resolved by identity, not by matching symbol names, which drift between releases.

Reachability is a fixpoint over the call graph: each function gets the set of panic categories it can raise, unioned from everything it calls. Drop glue is followed. Suppression removes categories before that propagation runs, and cleanup paths are gated on the panic that unwinds into them. A panic that cannot unwind out of its function reaches callers as an abort, which no catch contains. That happens in a function that must not unwind, in a cleanup block, and in a build whose panics abort.

Checks that are not in the build are not reported. The standard library ships one copy of its MIR for every crate that uses it, so a body can carry an overflow check or a precondition check that the crate being analysed compiles away, and a check written against size_of::<T>() is still a branch there even though it settles to a constant for every real T. Each body is folded against the arguments it was reached with and the settings of the build in front of it, the way codegen resolves them, so a branch neither can take is not walked. A test carries into the arm it guards, so a division below if divisor != 0 raises nothing.

Folding reads across a call rather than stopping at one. A callee is walked with what the call site knows about its arguments, so a value it returns carries a range with it and a precondition it checks can be settled by the caller that satisfies it: left / right.max(1) divides by something that cannot be zero, and v[i] under if v.len() >= 4 is in range for i below four. What a structure holds travels the same way, into a call and back out of one, so the size a chunks_exact(4) was built with is still four where the iterator's own arithmetic reads it. A call is read for what it raises as well as for what it returns: one whose every reachable block was found unable to raise leaves nothing behind, and neither does the cleanup path only a raise could have reached. An operation the compiler defines rather than a body raises nothing at all, so an atomic read whose ordering is written at the call site keeps none of the arms that reject the orderings it is not. What folding a callee found is kept, under the body and the claims it was handed, so the check the standard library writes under every slice read is folded once rather than at every site, and a site short of budget reads the answer a fuller walk found. A callee that no path returns from under the arguments it was handed never comes back, so nothing written after the call runs on that path: the panic it raises instead is the call's own.

How long a slice is travels with it. An array unsized to a slice is as long as its type says, a slice built from a pointer and a count is as long as the count, and a guard that measures two lengths against each other settles the check a copy between those two slices writes. An ordering against a length survives the arithmetic done to it: len - 1 and at + 1 are still measured against the same slice, i.min(len - 1) keeps the tighter of the two bounds it was handed, and a value below one that is itself below a length is below that length too. Two slices cut to one length are as long as each other, whether the length was named or worked out. A length a container keeps as a field is ordered the same way as one a slice carries, so v[at] under if at < v.len() is in range for a vector, a deque or a string, whichever of the two names the check reads it by. A byte string, or a slice a constant holds, is as long as the constant says.

A guard between two values the analysis cannot settle still orders the pair, and that is what the check between the two ends of v[start..end] asks: under start <= end, it cannot fail. One such ordering is followed through another, so an index below a bound that is itself at most a length is below that length, and an index below one slice is inside a second slice found to be as long.

How far under a length a value sits is kept as a count rather than a yes or no. i + 16 <= v.len() leaves i sixteen short of the length, i + 3 is then thirteen short and in range, and stepping i by sixteen leaves it at most the length, which is where the next turn of the loop starts from. The count only carries where the arithmetic cannot wrap, which a value under the length of a slice of sized elements guarantees: such a slice is at most half the address space long.

A comparison is read from both sides and for what each side's range says about the other, so lo < n leaves n above zero for an unsigned pair and the division written under that guard cannot fail. Each arm reads the end its own comparison points at rather than the other arm's end turned round, since what fails a < b is a >= b, and that bounds a from below by the bottom of b and not at all from above. A value is also compared with the one it was reached from, which is what settles the order check &v[at..at + 4] writes over its two ends.

Where two arms of a branch meet, what both leave behind survives as a range instead of being given up, and a claim still moving after they have met is pushed out to the nearest value the body compares against rather than straight to the end of its type, so a counter a loop keeps below a constant keeps that bound.

A claim belongs to the place it was read from rather than to whichever local happened to hold it, so a guard on self.pos still stands at the next read of that field, and a write to it, a call, or a pointer that could be aimed at it takes the claim away again. A pointer counts from where it is taken, so what a guard proved about a local before its address was handed out still stands up to that point. The element an index names is such a place, and a write to the index names a different one. A shared reference is not such a pointer, since nothing is written through one, and neither is a pointer taken through another: storing into v[i] cannot change how long v is. Values carry what their own type says: a byte is an index every table of two hundred and fifty six has room for, a character reaches no further than the last code point, and a pointer taken of a place holds an address, so the null check written under NonNull::new cannot fail. An enum carries which variant it holds, which is what folds a match and what makes unwrap of a value built as Some reach nothing at all; one written as a niche has no tag of its own, so a value proved apart from the pattern that stands for the empty variant is read as the variant that carries one. A branch that names every value its condition can hold leaves nothing for the arm written to cover the rest, which is what folds the match on two masked bits behind the standard library's packed IO error.

The driver injects -Zalways-encode-mir. Without it, a dependency keeps MIR only for generic and small items, so its concrete functions are opaque and the panics inside them cannot be seen.

Limitations

Read these before trusting a clean result.

• The default standard library is partly opaque. Concrete functions in std ship without MIR, so panics inside them are reported as unknown rather than proven absent. --std full rebuilds it from source with its bodies kept, which costs one build per toolchain: the tree is cached under the user's cache directory (PANICGRAPH_CACHE overrides where) and shared by every project on the machine. check and baseline do this by default, because a gate is read by its category names: with the shipped library a reachable unwrap reports as unknown. It does not remove unknown, it names it, so expect the same functions reported with sharper reasons.
• unknown is not clean. It means the analysis could not see inside something. check --fail-on-unknown refuses to treat the two alike.
• Dynamic dispatch is not resolved, only named. A dyn Trait call reports dyn-call, and so does dropping a trait object. A function pointer call reports fn-pointer. --candidates expands both: every concrete implementation of the trait whose type the reachable code makes into a trait object, and every reachable function or closure made into a pointer of a matching signature, joins the graph as a candidate edge, so the report shows what the call could actually do. The category stays either way, because candidates narrow the unknown rather than close it, and --static-only still drops the edges through objects and pointers entirely. A call a generic function makes through one of its bounds reports generic-bound, since which implementation runs is the caller's choice. Each of these names where visibility ended; --suppress assumed assumes them all, and check --fail-on-unknown refuses them all.
• This is a may-panic analysis. A panic that is unreachable for reasons the compiler cannot see is still reported. It answers "could this panic", not "will it". Folding settles a check against constants, against what a branch above it proves, against what a type admits, against how long a slice is, and against what walking a callee shows it returns or cannot raise. A bound a guard re-establishes on every turn of a loop is followed, and so is what a guard leaves to spare: i + 16 <= v.len() puts v[i + 3] in range once i is known to be no larger than the length, which is what rules out the sum wrapping round. The guard on the sum alone does not, since in a build without overflow checks the sum can wrap. An invariant held further out is still reported: one a caller establishes and the callee only assumes, and one a structure keeps across the methods that maintain it. A function that panics for some input is reported whatever its callers do, which is the honest answer for the function and the reason a caller that rules the input out is cleared separately.
• The toolchain is pinned. The driver links against compiler internals, which have no stable interface, so it is built for one nightly at a time. Updating the toolchain means reinstalling; the tool says so rather than leaving the loader to report a missing library.

License

Copyright 2026 Khashayar Fereidani.

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.