Error Handling Highlights Summary

Every highlight bullet from the 11 pages in this section, gathered on one page and grouped by the page it came from.

The Rust Error-Handling Philosophy

• Result and Option are ordinary enums - failure is data, not a separate control-flow channel
• Rust splits errors into two kinds: recoverable (Result) and unrecoverable (panic!)
• The ? operator is sugar for an early return on Err, nothing more exotic
• A function's signature tells you whether it can fail, before you read a line of its body

Error Handling Basics

• Use Option for missing values, not error details
• Use Result for recoverable errors with error details
• Match on Result to handle Ok and Err variants
• unwrap and expect panic on Err, use only for prototypes
• The ? operator propagates errors from Result
• Combine Option and Result for complex error scenarios

The ? Operator

• The ? operator early-returns Err and unwraps Ok values
• It automatically converts errors via the From trait
• Use ? in fallible functions returning Result to avoid nested match
• Ensure the return type implements From for each error source
• Using ? in main requires fn main() -> Result<(), E>
• ? on Option in Result functions needs compatible types or ok_or

panic! vs Recoverable Errors

• Use panic! for unrecoverable bugs or invariant violations
• Use Result for expected failures callers can handle
• Avoid panic! for control flow; use Result or Option
• Never panic across FFI boundaries unless explicitly caught
• Use get(i) for user indices to avoid panicking
• Document intentional panics using rustdoc's # Panics section

Custom Error Types

• Define error enums to wrap underlying failures
• Implement std::error::Error, Display, and From for errors
• Use From implementations for ergonomic ? operator usage
• Use #[non_exhaustive] on public enums for semver compatibility
• Avoid string-only errors; use typed enum variants instead
• Map internal errors to public enums to prevent semver breakage

thiserror

• Use thiserror for public library error types to reduce boilerplate
• Derive Display, Error, and From traits for error enums
• Use #[from] to generate From implementations for error variants
• Use #[error("...")] to format the Display output for an error
• Treat #[error] messages as API; changes are semver for human readers
• Use anyhow for application-level errors, thiserror for libraries

anyhow

• Use anyhow for CLIs, servers, and application binaries
• Do not use anyhow in public library APIs
• Use with_context for lazy context allocation
• Enable RUST_BACKTRACE for backtraces
• Downcast anyhow::Error in tests to avoid fragile display text
• anyhow::Error is Send + Sync + 'static

Error Context & Backtraces

• Attach context as errors bubble up to understand failures
• Enable RUST_BACKTRACE=1 for panics and some error types
• Log errors once at the boundary with the full chain
• Capture backtraces only on error, not on success paths
• Redact sensitive information like tokens from error context
• Use #[source] attribute with thiserror for proper error chaining

Option Combinators

• Use Option combinators to transform and chain optional values
• Use map and as_ref to avoid moving values
• unwrap_or_else provides a lazy default value
• Avoid unwrap in production code as it panics on None
• Use flatten for nested Option<Option<T>>
• and replaces with a constant Option, and_then chains operations

Fallible Iterators & collect()

• Collect an iterator of Results into a single Result
• collect() short-circuits on the first Err encountered
• Use collect::<Result<Vec<T>, E>>() to specify the target type
• Partial success is silently dropped when collect() stops
• Consider try_for_each for fallible iteration without collecting
• Manual for loops offer clarity for side effects

Error Handling Best Practices

• Libraries use typed errors, applications use context-rich anyhow/eyre
• Review before adding unwrap to production paths
• Use thiserror for public error enums in libraries
• Avoid anyhow in public APIs; consumers need typed errors
• Use anyhow or eyre at the binary boundary for applications
• Return non-zero exit codes from CLI applications