eyre

eyre is a fork of the popular anyhow crate that adds one key capability: swappable report handlers. Applications use Result<T, eyre::Report> (aliased eyre::Result<T>) to propagate any error implementing std::error::Error with ?, wrap lower-level errors with context via .wrap_err(), and construct one-off errors with the eyre!/bail! macros — the same ergonomics anyhow popularized.

What sets eyre apart is the EyreHandler trait: the actual formatting and captured metadata of an error report is pluggable, so companion crates can customize it. color-eyre (also maintained in this repository) captures a backtrace and tracing_error::SpanTrace, then pretty-prints the report with colorized output and a Help trait for attaching suggestions; simple-eyre strips capture down to nothing; stable-eyre swaps the backtrace implementation for one that works on stable Rust. eyre ships an anyhow-compatibility feature flag so it can be used as a near drop-in replacement in either direction.

What You Get

• eyre::Result<T> (= Result<T, eyre::Report>) as a drop-in return type for fallible functions, propagated with ?
• .wrap_err()/.wrap_err_with() (via the ResultExt trait) to attach contextual messages while preserving the error chain
• The eyre!/bail! macros for constructing one-off, string-interpolated errors with a single line
• Automatic backtrace capture on rustc-1.65+, accessible via std::backtrace env vars (RUST_BACKTRACE, RUST_LIB_BACKTRACE)
• A pluggable EyreHandler trait so companion crates (color-eyre, simple-eyre, stable-eyre) can customize what’s captured and how reports are formatted

Common Use Cases

• Application-level error handling where the goal is reporting a clear failure chain to the user or logs, not matching on specific error variants
• Wrapping lower-level I/O, parsing, or network errors with human-readable context (.wrap_err("Failed to read config"))
• Pretty, colorized terminal error reports in CLI tools via the companion color-eyre crate
• Migrating between anyhow and eyre codebases using the built-in compatibility layer

Under The Hood

Architecture: The crate’s core is eyre::Report (eyre/src/error.rs, ~930 lines), a boxed trait object that owns the source error, an optional captured backtrace, and a handler implementing EyreHandler. eyre/src/context.rs implements the ResultExt/wrap_err machinery that layers new context onto an existing error while preserving the source() chain. eyre/src/macros.rs implements eyre!/bail!/ensure! via declarative macros, and eyre/src/kind.rs uses an autoref-based trait dispatch trick (shared with anyhow) so eyre!() can accept either a Display-only value or a full std::error::Error. The repository is a Cargo workspace with eyre, color-eyre, color-spantrace, and simple-eyre as separate member crates, letting the handler customization live in independently-versioned companion packages rather than feature flags on the core crate.

Tech Stack: Pure Rust (98.6%), edition = 2024, rust-version = 1.85.0 per the workspace Cargo.toml. Optional dependencies are gated by feature flags — owo-colors (v4.3) is pulled in for color-eyre’s colorized output, indenter for report indentation, and an anyhow compatibility feature re-exports renamed APIs under anyhow’s original names for drop-in interoperability.

Code Quality: The eyre crate has a dedicated tests/ directory with focused suites — test_source.rs, test_convert.rs, test_fmt.rs, test_macros.rs, test_chain.rs, test_autotrait.rs, test_location.rs, test_downcast.rs, and a compiletest.rs for compile-fail/UI testing of macro error messages. With 68 contributors and maintainers including dtolnay (author of the original anyhow), the codebase follows established Rust error-handling crate conventions closely.

API Design: The README explicitly documents when not to use eyre::Report as a public library API (it erases error type information, making downstream error matching brittle), steering the crate firmly toward application-code use — a rare and useful piece of self-aware API guidance. The eyre!/bail!/wrap_err surface requires almost no boilerplate for the common case, and the anyhow compatibility layer means teams can adopt eyre without rewriting existing anyhow-based error-handling code.