Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

rust-errors

Design Rust error types and panic policy — Result over unwrap, thiserror for libraries, anyhow for binaries, context that survives the call stack. Use when code calls unwrap or expect outside tests, when designing or refactoring an error enum, when choosing between thiserror and anyhow, or when the user asks how errors should be handled or propagated.

rewrite-rs · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add rewrite-rs/skills --skill rust-errors

About this skill


name: rust-errors description: Design Rust error types and panic policy — Result over unwrap, thiserror for libraries, anyhow for binaries, context that survives the call stack. Use when code calls unwrap or expect outside tests, when designing or refactoring an error enum, when choosing between thiserror and anyhow, or when the user asks how errors should be handled or propagated.

Rust Errors

An error type is a contract about what can go wrong and what the caller does about it: which failures panic, which become a Result, which shape the error takes, how much context survives the call stack. Making the failure impossible is /type-driven-design; whether shape changes break callers, /rust-api-design.

The panic policy

unwrap and expect are assertions about invariants, not error handling. Acceptable: in tests, in main for a startup precondition, in a developer-facing tool where a non-fatal failure may simply stop the run, in a const context where no Result can be returned, in a method whose name tells the caller it unwraps on request (unwrap_*, expect_*), and after a check the compiler cannot see — where expect names the invariant and carries the values. Unacceptable: in library code on any input-derived value, or anywhere the justification is "this can't fail" without saying why.

Not every failure is a Result. A broken internal invariant with no caller-recoverable path should panic — the program is already in a state the type system promised it would not reach. Input validation is the opposite: whatever the input, the caller can respond, so it is always a Result. Where a panic for misuse is justified, offer a fallible sibling beside the panicking function; the pairing and the rest of the panic detail are in PANICS.md.

Option or Result? When absence is the single, obvious way an operation can fail and nobody needs to know why (a lookup, checked_add), return Option. When the failure has a cause the caller could report or branch on, return Result; an Option there throws the cause away and the caller can only guess.

Result all the way to a boundary

Errors propagate with ? to the layer that can actually decide — retry, report, exit. ? converts through From, which is why a #[from] on an enum variant removes a map_err closure at every call site. Reach for map_err only to convert an error from a type that has no From into yours, or to add context at that one call site; a map_err that only wraps one variant of your own type is a missing From impl.

Which shape: the boundary decides

One question settles it: does this error cross a public API boundary you will maintain across releases?

No — an internal crate, a closed set of failures, an error the caller only ever prints — it is an enum, and the enum is the cheaper, better answer:

#[derive(Debug, thiserror::Error)]
enum LoadError {
    #[error("cannot read {path}")]
    Read { path: PathBuf, #[source] source: std::io::Error },
    #[error("malformed config in {path}")]
    Parse { path: PathBuf, #[source] source: toml::de::Error },
}

Yes — a published library whose callers upgrade without editing their code — it is a struct wrapping a private kind, exposing the questions callers actually ask:

pub struct ConfigError { kind: ErrorKind }

impl ConfigError {
    pub fn is_not_found(&self) -> bool { /* match on the private kind */ }
    pub fn path(&self) -> &Path { /* ... */ }
}

The full struct pattern, compiling, is in ERROR-TYPES.md. A public library leans toward situation-specific error structs like this one, each named for what went wrong, not one crate-wide enum; the same struct is reused by similar functions (one parse error for the JSON and the TOML entry points) instead of minting a new type per function. The enum stays the right answer for an internal or closed set.

The public enum fails at that boundary in four independent ways: a variant like Parse(toml::de::Error) promises for ever which TOML crate you use; adding a failure mode breaks caller matches; #[non_exhaustive] does not save it, because it forces every caller into a _ => arm from day one and so removes the exhaustive matching that was the reason to expose an enum; and it pushes work onto callers, who re-derive "the config file is missing" from ConfigError::Io(e) if e.kind() == NotFound. The precedent is std::io::Error, which is exactly this pattern.

thiserror still does the mechanical work either way — #[source] chaining and Display forwarding. Binaries use anyhow (or eyre, its close equivalent with pluggable report handlers): a binary error is a message a human reads once, so a boxed dynamic error with context is enough. A binary large enough to have internal library crates uses thiserror inside them and anyhow only at the top — and the whole application settles on a single top-level error type instead of mixing several. anyhow in a published library forces every downstream caller to give up matching on concrete types — that is the actual reason for the split, not taste.

Error taxonomy

Split the enum by what the caller does about it, not by where it was raised. If two variants always get identical handling, they are one variant. If one variant is retryable and another fatal, they must be distinguishable without string-matching a message — an is_retryable() or kind() accessor on a coarse enum. On a public struct error the growth question does not arise, because the kind is private and adding to it is not a breaking change; #[non_exhaustive] is for the enum that is public despite the guidance above, buying non-breaking growth at the cost of exhaustive matching. The semver rules live in /rust-api-design.

Panics that are the right answer

Panic means stop the program, not "return an error loudly": a detected bug — a violated internal invariant — panics rather than returning an Error, because there is no cal

Read the complete source ↗