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.
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)
- 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.
- 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).
- 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
- 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.
- Applications use
anyhow; libraries use thiserror. Do not pull anyhow into
a reusable library's signatures.
- Add context at each layer in application code:
.context("...") /
.with_context(|| ...) turns "No such file or directory" into a traceable chain.
#[from] for zero-boilerplate conversion, so ? lifts a source error into your
enum. #[from] implies #[source] — never write both.
- 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 |
Building a typed error enum for a library API |
| anyhow (applications) |
anyhow-applications.md |
Handling errors in a binary / top-level app |
| Error design |
error-design.md |
Shaping enums, #[from] conversion, recoverable vs panic, the anyhow/thiserror boundary |
Templates
| Template |
Load when |
| library-error.md |
Need a complete thiserror library error module |
| application-error.md |
Need a complete anyhow application entry point with context |
Validation Checklist
1---2name: rust-error-handling3description: 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).4versions:5 rust: "1.96.1"6 thiserror: "2"7 anyhow: "1"8references: references/thiserror-libraries.md, references/anyhow-applications.md, references/error-design.md, references/templates/library-error.md, references/templates/application-error.md9related-skills: rust-core-language10metadata:11 source: https://skillmd.com/skills/fusengine/rust-error-handling12---1314<objective>15This skill covers the thiserror-for-libraries, anyhow-for-applications split in Rust:16building typed error enums with #[derive(Error)] for library APIs callers can match on,17using anyhow::Result with .context()/.with_context() in application code, and18zero-boilerplate error conversion via #[from].1920It also covers the recoverable-errors-vs-panics decision — Result for anything a caller21could reasonably recover from, panic!/unwrap/expect reserved for broken invariants — and22the rule that anyhow::Error must never leak into a library's public API.2324Out of scope: general ownership/borrowing design belongs to rust-core-language;25async-runtime-specific error handling is not covered here.26</objective>2728# Rust Error Handling2930The consensus split: **thiserror for libraries, anyhow for applications.** A library31exposes a typed error its callers can `match`; an application wants one ergonomic error32type and rich context. Getting this boundary right is the whole discipline.3334## Agent Workflow (MANDATORY)35361. **fuse-ai-pilot:explore-codebase** — is this crate a library (published API, other37 code depends on it) or a binary/application? That answer picks the tool.382. **fuse-ai-pilot:research-expert** — confirm current `thiserror` / `anyhow` API39 before writing derives (verification chain: fuse-browser fast-path on40 `docs.rs/thiserror` and `docs.rs/anyhow` → Context7 → Exa).413. After writing, run **fuse-ai-pilot:sniper** and `cargo clippy`.4243## The rule4445| Crate kind | Tool | Why |46|------------|------|-----|47| **Library** (others depend on it) | `thiserror` | Typed `enum`, `#[derive(Error)]`, callers can `match` on variants |48| **Application** (binary, top level) | `anyhow` | `anyhow::Result<T>`, `?` everywhere, `.context()` for breadcrumbs |49| **Simple / dep-free** | hand-written `std::error::Error` | No dependency when one or two variants suffice |5051## Critical Rules52531. **Never expose `anyhow::Error` in a library's public API.** It erases the type, so54 callers cannot match or handle specific failures. Return a typed `enum` error.55 thiserror is designed to not appear in your public API — switching to/from a56 hand-written impl is not a breaking change.572. **Applications use `anyhow`; libraries use `thiserror`.** Do not pull `anyhow` into58 a reusable library's signatures.593. **Add context at each layer** in application code: `.context("...")` /60 `.with_context(|| ...)` turns "No such file or directory" into a traceable chain.614. **`#[from]` for zero-boilerplate conversion**, so `?` lifts a source error into your62 enum. `#[from]` implies `#[source]` — never write both.635. **Errors are values; panics are bugs.** Use `Result` for anything a caller could64 reasonably recover from. Reserve `panic!`/`unwrap`/`expect` for broken invariants.6566## Reference Guide6768### Concepts6970| Topic | Reference | Load when |71|-------|-----------|-----------|72| thiserror (libraries) | [thiserror-libraries.md](references/thiserror-libraries.md) | Building a typed error enum for a library API |73| anyhow (applications) | [anyhow-applications.md](references/anyhow-applications.md) | Handling errors in a binary / top-level app |74| Error design | [error-design.md](references/error-design.md) | Shaping enums, `#[from]` conversion, recoverable vs panic, the anyhow/thiserror boundary |7576### Templates7778| Template | Load when |79|----------|-----------|80| [library-error.md](references/templates/library-error.md) | Need a complete thiserror library error module |81| [application-error.md](references/templates/application-error.md) | Need a complete anyhow application entry point with context |8283## Validation Checklist8485- [ ] Library errors are a typed `enum` deriving `thiserror::Error` — no `anyhow` in the public API86- [ ] Application code returns `anyhow::Result<T>` and adds `.context(...)`87- [ ] `#[from]` used for source conversions; no redundant `#[source]` alongside it88- [ ] `?` used instead of `unwrap()` on fallible values89- [ ] Panics only guard genuine invariants, with a reason90- [ ] `cargo clippy` clean, sniper passed