rust-error-handling · diff
git:20260715.2c1b77f to git:20260729.3b91eed
15 added, 1 removed. Audit A to A.
---
name: rust-error-handling
- description: Use when designing Rust error handling — picking thiserror for libraries vs anyhow for applications, building typed error enums, converting errors with #[from], and deciding recoverable errors vs panics. Do NOT use for general ownership/borrowing (use rust-core-language) or async runtime errors specifically.
+ description: Use when designing Rust error handling — thiserror vs anyhow, typed error enums, #[from] conversions, or recoverable errors vs panics. Not for ownership/borrowing (rust-core-language).
versions:
rust: "1.96.1"
thiserror: "2"
anyhow: "1"
references: references/thiserror-libraries.md, references/anyhow-applications.md, references/error-design.md, references/templates/library-error.md, references/templates/application-error.md
related-skills: rust-core-language
---
+
+ <objective>
+ This skill covers the thiserror-for-libraries, anyhow-for-applications split in Rust:
+ building typed error enums with #[derive(Error)] for library APIs callers can match on,
+ using anyhow::Result with .context()/.with_context() in application code, and
+ zero-boilerplate error conversion via #[from].
+
+ It also covers the recoverable-errors-vs-panics decision — Result for anything a caller
+ could reasonably recover from, panic!/unwrap/expect reserved for broken invariants — and
+ the rule that anyhow::Error must never leak into a library's public API.
+
+ Out of scope: general ownership/borrowing design belongs to rust-core-language;
+ async-runtime-specific error handling is not covered here.
+ </objective>
# Rust Error Handling
The consensus split: **thiserror for libraries, anyhow for applications.** A library
exposes a typed error its callers can `match`; an application wants one ergonomic error
type and rich context. Getting this boundary right is the whole discipline.
## Agent Workflow (MANDATORY)
1. **fuse-ai-pilot:explore-codebase** — is this crate a library (published API, other
code depends on it) or a binary/application? That answer picks the tool.
2. **fuse-ai-pilot:research-expert** — confirm current `thiserror` / `anyhow` API
before writing derives (verification chain: fuse-browser fast-path on
`docs.rs/thiserror` and `docs.rs/anyhow` → Context7 → Exa).
3. After writing, run **fuse-ai-pilot:sniper** and `cargo clippy`.
## The rule
| Crate kind | Tool | Why |
|------------|------|-----|
| **Library** (others depend on it) | `thiserror` | Typed `enum`, `#[derive(Error)]`, callers can `match` on variants |
| **Application** (binary, top level) | `anyhow` | `anyhow::Result<T>`, `?` everywhere, `.context()` for breadcrumbs |
| **Simple / dep-free** | hand-written `std::error::Error` | No dependency when one or two variants suffice |
## Critical Rules
1. **Never expose `anyhow::Error` in a library's public API.** It erases the type, so
callers cannot match or handle specific failures. Return a typed `enum` error.
thiserror is designed to not appear in your public API — switching to/from a
hand-written impl is not a breaking change.
2. **Applications use `anyhow`; libraries use `thiserror`.** Do not pull `anyhow` into
a reusable library's signatures.
3. **Add context at each layer** in application code: `.context("...")` /
`.with_context(|| ...)` turns "No such file or directory" into a traceable chain.
4. **`#[from]` for zero-boilerplate conversion**, so `?` lifts a source error into your
enum. `#[from]` implies `#[source]` — never write both.
5. **Errors are values; panics are bugs.** Use `Result` for anything a caller could
reasonably recover from. Reserve `panic!`/`unwrap`/`expect` for broken invariants.
## Reference Guide
### Concepts
| Topic | Reference | Load when |
|-------|-----------|-----------|
| thiserror (libraries) | [thiserror-libraries.md](references/thiserror-libraries.md) | Building a typed error enum for a library API |
| anyhow (applications) | [anyhow-applications.md](references/anyhow-applications.md) | Handling errors in a binary / top-level app |
| Error design | [error-design.md](references/error-design.md) | Shaping enums, `#[from]` conversion, recoverable vs panic, the anyhow/thiserror boundary |
### Templates
| Template | Load when |
|----------|-----------|
| [library-error.md](references/templates/library-error.md) | Need a complete thiserror library error module |
| [application-error.md](references/templates/application-error.md) | Need a complete anyhow application entry point with context |
## Validation Checklist
- [ ] Library errors are a typed `enum` deriving `thiserror::Error` — no `anyhow` in the public API
- [ ] Application code returns `anyhow::Result<T>` and adds `.context(...)`
- [ ] `#[from]` used for source conversions; no redundant `#[source]` alongside it
- [ ] `?` used instead of `unwrap()` on fallible values
- [ ] Panics only guard genuine invariants, with a reason
- [ ] `cargo clippy` clean, sniper passed