Rust Error Handling

---
name: rust-error-handling
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