This library provides eyre::ErrReport, a trait object based error type for easy idiomatic error handling in Rust applications.

Details

• Use Result<T, eyre::ErrReport>, or equivalently eyre::Result<T>, as the return type of any fallible function.

  Within the function, use ? to easily propagate any error that implements the std::error::ErrReport trait.

  use eyre::Result;
  
  fn get_cluster_info() -> Result<ClusterMap> {
      let config = std::fs::read_to_string("cluster.json")?;
      let map: ClusterMap = serde_json::from_str(&config)?;
      Ok(map)
  }

• Attach context to help the person troubleshooting the error understand where things went wrong. A low-level error like "No such file or directory" can be annoying to debug without more context about what higher level step the application was in the middle of.

  use eyre::{WrapErr, Result};
  
  fn main() -> Result<()> {
      ...
      it.detach().wrap_err("Failed to detach the important thing")?;
  
      let content = std::fs::read(path)
          .wrap_err_with(|| format!("Failed to read instrs from {}", path))?;
      ...
  }

  Error: Failed to read instrs from ./path/to/instrs.json
  
  Caused by:
      No such file or directory (os error 2)
  

• Downcasting is supported and can be by value, by shared reference, or by mutable reference as needed.

  // If the error was caused by redaction, then return a
  // tombstone instead of the content.
  match root_cause.downcast_ref::<DataStoreError>() {
      Some(DataStoreError::Censored(_)) => Ok(Poll::Ready(REDACTED_CONTENT)),
      None => Err(error),
  }

• A backtrace is captured and printed with the error if the underlying error type does not already provide its own. In order to see backtraces, the RUST_LIB_BACKTRACE=1 environment variable must be defined.

• Eyre works with any error type that has an impl of std::error::Error, including ones defined in your crate. We do not bundle a derive(Error) macro but you can write the impls yourself or use a standalone macro like thiserror.

  use thiserror::Error;
  
  #[derive(Error, Debug)]
  pub enum FormatError {
      #[error("Invalid header (expected {expected:?}, got {found:?})")]
      InvalidHeader {
          expected: String,
          found: String,
      },
      #[error("Missing attribute: {0}")]
      MissingAttribute(String),
  }

• One-off error messages can be constructed using the eyre! macro, which supports string interpolation and produces an eyre::ErrReport.

  return Err(eyre!("Missing attribute: {}", missing));

No-std support

In no_std mode, the same API is almost all available and works the same way. To depend on Eyre in no_std mode, disable our default enabled "std" feature in Cargo.toml. A global allocator is required.

[dependencies]
eyre = { version = "0.2", default-features = false }

Since the ?-based error conversions would normally rely on the std::error::ErrReport trait which is only available through std, no_std mode will require an explicit .map_err(ErrReport::msg) when working with a non-Eyre error type inside a function that returns Eyre's error type.