Error Handling Best Practices

How to Use This List

• Libraries: typed errors. Applications: context-rich anyhow/eyre.
• Review before adding unwrap to production paths.

A - Libraries

• Use thiserror for public error enums. Stable matchable variants.
• Implement Error + Display + From for sources. Enable ? chains.
• Avoid anyhow in public APIs. Consumers need typed errors.
• Mark extensible enums #[non_exhaustive]. Semver-friendly evolution.
• Document which variants are transient vs permanent. Retry logic depends on it.

B - Applications

• Use anyhow or eyre at binary boundary. Attach context liberally.
• Return non-zero exit codes from CLI. Map Err to code 1+.
• Log full error chain once at boundary. Avoid duplicate context layers.
• Map errors to HTTP status in handlers only. Keep domain errors transport-agnostic.
• Enable backtraces in staging CI failures. RUST_BACKTRACE=1.

C - Panics and unwrap

• No unwrap in library fallible paths. Return Result.
• Use expect with message only when invariant documented. Tests and provable logic.
• Prefer ? over match boilerplate. Clearer happy path.
• Use debug_assert! for dev invariants. Not user validation.
• Never panic across FFI. Return error codes.

D - Options and Results

• Option for optional, Result for failure. Do not conflate.
• Use combinators before deep match nesting. Readability.
• Collect Result iterators with short-circuit awareness. Document partial failure policy.
• Add context at operation boundaries. File paths, user ids, request ids.
• Test error paths, not only Ok. Include invalid input tests.

FAQs

Related

• Error Handling Basics
• thiserror
• anyhow
• Error Strategy

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.