po4yka/rust-skills / skills/rust-panic-safety
rust-panic-safety
VerifiedUse when guarding an extern "C", extern "system", or JNI entry point with catch_unwind, choosing panic = "unwind" or "abort", installing a panic hook, disposing of a panic payload, fixing an UnwindSafe bound with AssertUnwindSafe, or triaging an abort such as "panic in a function that cannot unwind". Also use when a panic can escape a foreign callback, spawned task, thread, or Drop, or when replacing unwrap or expect on an FFI-reachable path. Owns the panic policy at a C ABI boundary.
Rust panic safety
Find the boundaries
# Every function that foreign code can call. A bare `extern fn` is `extern "C"`.
rg -n 'extern "(C|system|C-unwind|system-unwind)"|extern fn|#\[jni_mangle|native_method!' --type rust
# Every symbol that leaves the crate unmangled.
rg -n '#\[unsafe\(no_mangle\)\]|#\[no_mangle\]|#\[export_name|#\[unsafe\(export_name' --type rust
# Every guard that already exists.
rg -n 'catch_unwind|AssertUnwindSafe|with_env' --type rust
# Every panic strategy declared in the tree: manifests, config files, and rustflags.
rg -n --hidden 'panic\s*=\s*"?(abort|unwind)' \
-g '**/Cargo.toml' -g '**/.cargo/config.toml' -g '**/.cargo/config'
Compare lists 1 and 3 from this checkout. native_method! generates a with_env guard
unless it is raw or sets catch_unwind = false. Report an entry with neither a
guard nor a documented abort policy (Rule 1).
Verify a boundary change
| Claim | Check | What a green result does not prove |
|---|---|---|
| Every entry point has a guard | The inventory above, list 1 against list 3 | That the guard maps every outcome |
| The shipped build unwinds | cargo rustc --locked -p <boundary-crate> --lib --release --target <shipping-triple> -- --print cfg prints panic="unwind" | That every entry point has a guard |
| A panic returns the reserved code | A Rust test that calls the extern function with a forced panic and asserts the reserved code | That the shipped build unwinds |
| No new unguarded panic sites | cargo clippy --locked --all-targets -- -D warnings with -p for every crate on the FFI path, with the lints below | That each kept .expect invariant holds; overflow, panicking std APIs (split_at, RefCell::borrow_mut), and dependency panics |
| No std-checked precondition fires on tested paths | cargo test --locked in the default debug profile | Soundness: run Miri, or ASan where Miri cannot run the foreign code (the rust-sanitizers-miri skill) |
Use the shipping --target, --profile, and environment for --print cfg.
Without --target, it can print unwind for a shipped abort build.
Read references/panic-strategy.md (section "Check the shipped strategy") for every source it
reflects. When the boundary decodes untrusted input, fuzz the decoder behind it: a guard turns
each panic into a status code and hides it from every other test.
Done when
- Every inventory entry point has a guard, or a comment that states abort as its policy.
- Every
externbody is a guard plus a delegation call to a testable plain Rust function. - The
--print cfgcheck printspanic="unwind"if any guard usescatch_unwind. - The panic exit differs from every domain error exit.
- The boundary discards the payload through a second guard. Only a run-once loader such as
JNI_OnLoadcan leak it instead, withManuallyDrop::new, nevermem::forget. - The hook is installed once and emits only a closed site code plus numeric location.
- Every
AssertUnwindSafehas a comment that names the invariant. - Every crate on the FFI path denies
clippy::unwrap_usedandclippy::panic. - No
Dropcan panic. Every spawned task or thread reports its panic at a join point or through its own guard.
Failure triage
| Symptom | Likely cause | Action |
|---|---|---|
SIGABRT on Unix, or 0xC0000409 on Windows; stderr shows panic in a function that cannot unwind | A panic reached an unguarded extern "C" or extern "system" function | Add the guard, or document abort as its policy |
catch_unwind never returns Err, process still dies | The build uses panic = "abort" | Run the --print cfg check with the shipping --target; fix the source it names |
catch_unwind returns Ok, work silently missing | The panic was on another thread or task | Join the handle and inspect JoinError |
fatal runtime error: Rust cannot catch foreign exceptions, aborting | A foreign exception reached catch_unwind | Catch it on the foreign side |
panic in a destructor during cleanup, then thread caused non-unwinding panic. aborting. | A Drop implementation panicked while a panic was in flight | Make the Drop infallible |
| The boundary catches a panic, then aborts | Dropping the caught payload panicked | Drop the payload inside a second guard; keep a second payload in ManuallyDrop |
memory allocation of N bytes failed, then abort | Allocation failure, not a catchable panic | Bound the size; use Vec::try_reserve for input-driven buffers |
unsafe precondition(s) violated: ..., then abort, with debug assertions on | An unsafe call broke its precondition: undefined behaviour, not a panic path | Fix the call. Keep cargo test --locked -p <crate> in the debug profile: without debug assertions the check is skipped and the UB runs |
| The panic record has no message or backtrace | The shipped privacy contract | Reproduce on the host with RUST_BACKTRACE=full, or symbolicate offline |
| Every later call fails with a poison error | An earlier panic poisoned a shared lock | Decide the poison policy; report the original panic |
building tests with panic=abort is not supported without -Zpanic_abort_tests | -C panic=abort in a rustflags source reaches the test build | Set the flag only in the shipping build command, or use nightly -Zpanic-abort-tests |
Panic location points into a macro or core | An index, a slice range, or an overflow | Reproduce with overflow-checks = true in a debug build |
Silent hazards
A test run rarely shows these defects.
- Treat every panic message as a log line: Android
panic = "abort"copies it into the tombstone, and UniFFI into the foreign exception. Never put secrets or user data in a panic,expect, orunreachable!message. Result::unwrapandResult::expectappend the error'sDebugtext. An error type on an FFI path must not carry input data inDebug, or the call must map the error before it panics.- The JNI
ThrowRuntimeExAndDefaultpolicy copies the error'sDisplaytext into the exception. Use a fixed-message policy when that text can carry input data. - Swift calls a non-throwing UniFFI export through
try!, so a panic there ends the app. Keep such exports panic-free. core::hint::unreachable_unchecked()with a wrong proof is undefined behaviour, not a panic. Use it only with aSAFETYcomment that proves the branch is impossible.
Rule 1: decide what a panic does at each foreign entry point
Since Rust 1.81, a panic that reaches an extern "C" or extern "system" function aborts the
process with panic in a function that cannot unwind: the host sees a native crash. Before 1.81
it was undefined behaviour, so a crate with an MSRV below 1.81 must guard every entry point.
This skill is the catalog's single home for this policy:
- Guard with
catch_unwindevery entry point whose caller must get an error instead of a dead process: the default for a JNI library, a plugin, or acdylibbehind Swift or C. - Leave a body unguarded only where an abort is the intended result, for example a callback in a standalone binary. Write that intent in a comment on the function.
- Use
extern "C-unwind"only when the other side can unwind through it, such as C++ built with exceptions. A Java, Swift, or-fno-exceptionsC caller cannot. - A foreign exception that unwinds into Rust through a function declared
extern "C"is undefined behaviour. Catch a C++ exception on the C++ side, or declare the importextern "C-unwind".
Choose the panic strategy before you write the guard
panic = "abort" silently turns every catch_unwind guard into dead code. Set
panic = "unwind" in the workspace-root [profile.release] when any entry point relies on
catch_unwind; a member manifest's profile has no effect, and tests always build with unwind.
Read references/panic-strategy.md when you set or review the panic key or its overrides.
What catch_unwind catches
std::panic::catch_unwind catches an unwinding panic that starts inside the closure, on the
same thread, after the panic hook runs. It does not catch a panic on another thread (join it),
a process abort (a panic in Drop during unwinding, an unsafe precondition(s) violated check,
an allocation failure), a stack overflow, or, in any reliable way, a foreign exception (catch it
on the foreign side).
Do not remove a guard for speed without a benchmark that shows its cost.
Read references/unwind-state.md when guarded code mutates shared state, holds a lock, or needs AssertUnwindSafe.
The guard pattern: hand-rolled C ABI
Return a status code, never a Result and never a panic. Reserve one code for a caught
panic so the caller can tell a domain error from a bug.
Read references/boundary-patterns.md (section "The guard pattern: hand-rolled C ABI") for the
complete extern "C" function, lib_render, and its discard_panic_payload helper.
Keep the extern body to a guard plus a delegation call. Put the logic in a plain Rust
function that the tests can call directly.
The payload's destructor can panic, so drop it inside a second guard, and leak a second payload
with ManuallyDrop (a bounded leak on the double-panic path only). Do not inspect or format
either payload.
Read references/boundary-patterns.md also when the entry point returns a pointer or an opaque
handle, writes out-parameters, is a callback that a foreign runtime invokes, or the crate needs a
macro-generated extern layer.
JNI, UniFFI, and the panic hook
Read references/jni-boundary.md for a JNI export or JNI_OnLoad, references/panic-hook.md for the panic hook, and the UniFFI section of references/boundary-patterns.md for a UniFFI export.
.unwrap() and .expect() on FFI-reachable paths
The rust-discipline skill owns the general unwrap and expect rule. On a path that a
foreign caller reaches, a panic kills the host process unless a guard catches it.
Never .unwrap() or .expect() there on a Result or Option that input or the environment
can make Err or None: propagate with ? and let the boundary map the error. Never write
.expect("should never happen"): state the invariant in the message, or model it in the type.
Deny clippy::unwrap_used, clippy::panic, clippy::todo, clippy::unimplemented, and
clippy::panic_in_result_fn in every crate on an FFI path. Set clippy::expect_used and
clippy::indexing_slicing to at least warn. Count the debt with the command in references/unwrap-audit.md ("Step 1"), never from memory,
and read that file when you roll these lints out.
Read the rollback guide for rollback with
DropGuard on Rust 1.100+.
Errors at the boundary
Keep the panic exit distinct from every error exit: a panic is a bug, an error is an expected
failure, and a shared code makes the crash report useless. Read the
typed-errors section of references/unwrap-audit.md when you design or map the error type of a
crate on an FFI path.
Shared state, tasks, and threads
Read the async section of references/boundary-patterns.md when a panic can start in a spawned task, a thread, or a future that block_on drives.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |