Skip to content

po4yka/rust-skills / skills/rust-panic-safety

rust-panic-safety

Verified

Use 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

ClaimCheckWhat a green result does not prove
Every entry point has a guardThe inventory above, list 1 against list 3That the guard maps every outcome
The shipped build unwindscargo 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 codeA Rust test that calls the extern function with a forced panic and asserts the reserved codeThat the shipped build unwinds
No new unguarded panic sitescargo clippy --locked --all-targets -- -D warnings with -p for every crate on the FFI path, with the lints belowThat each kept .expect invariant holds; overflow, panicking std APIs (split_at, RefCell::borrow_mut), and dependency panics
No std-checked precondition fires on tested pathscargo test --locked in the default debug profileSoundness: 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 extern body is a guard plus a delegation call to a testable plain Rust function.
  • The --print cfg check prints panic="unwind" if any guard uses catch_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_OnLoad can leak it instead, with ManuallyDrop::new, never mem::forget.
  • The hook is installed once and emits only a closed site code plus numeric location.
  • Every AssertUnwindSafe has a comment that names the invariant.
  • Every crate on the FFI path denies clippy::unwrap_used and clippy::panic.
  • No Drop can panic. Every spawned task or thread reports its panic at a join point or through its own guard.

Failure triage

SymptomLikely causeAction
SIGABRT on Unix, or 0xC0000409 on Windows; stderr shows panic in a function that cannot unwindA panic reached an unguarded extern "C" or extern "system" functionAdd the guard, or document abort as its policy
catch_unwind never returns Err, process still diesThe build uses panic = "abort"Run the --print cfg check with the shipping --target; fix the source it names
catch_unwind returns Ok, work silently missingThe panic was on another thread or taskJoin the handle and inspect JoinError
fatal runtime error: Rust cannot catch foreign exceptions, abortingA foreign exception reached catch_unwindCatch 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 flightMake the Drop infallible
The boundary catches a panic, then abortsDropping the caught payload panickedDrop the payload inside a second guard; keep a second payload in ManuallyDrop
memory allocation of N bytes failed, then abortAllocation failure, not a catchable panicBound the size; use Vec::try_reserve for input-driven buffers
unsafe precondition(s) violated: ..., then abort, with debug assertions onAn unsafe call broke its precondition: undefined behaviour, not a panic pathFix 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 backtraceThe shipped privacy contractReproduce on the host with RUST_BACKTRACE=full, or symbolicate offline
Every later call fails with a poison errorAn earlier panic poisoned a shared lockDecide 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 buildSet the flag only in the shipping build command, or use nightly -Zpanic-abort-tests
Panic location points into a macro or coreAn index, a slice range, or an overflowReproduce 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, or unreachable! message.
  • Result::unwrap and Result::expect append the error's Debug text. An error type on an FFI path must not carry input data in Debug, or the call must map the error before it panics.
  • The JNI ThrowRuntimeExAndDefault policy copies the error's Display text 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 a SAFETY comment 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_unwind every entry point whose caller must get an error instead of a dead process: the default for a JNI library, a plugin, or a cdylib behind 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-exceptions C 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 import extern "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.

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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall