fusengine/rust-error-handling

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 | 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

• [ ] 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