impl Error

fn new<E>(error: E) -> Self
where
    E: StdError + Send + Sync + 'static,

Create a new error object from any error type.

The error type must be threadsafe and 'static, so that the Error will be as well.

If the error type does not provide a backtrace, a backtrace will be created here to ensure that a backtrace exists.

fn msg<M>(message: M) -> Self
where
    M: Display + Debug + Send + Sync + 'static,

Create a new error object from a printable error message.

If the argument implements std::error::Error, prefer Error::new instead which preserves the underlying error's cause chain and backtrace. If the argument may or may not implement std::error::Error now or in the future, use anyhow!(err) which handles either way correctly.

Error::msg("...") is equivalent to anyhow!("...") but occasionally convenient in places where a function is preferable over a macro, such as iterator or stream combinators:

# mod ffi {
#     pub struct Input;
#     pub struct Output;
#     pub async fn do_some_work(_: Input) -> Result<Output, &'static str> {
#         unimplemented!()
#     }
# }
#
# use ffi::{Input, Output};
#
use anyhow::{Error, Result};
use futures::stream::{Stream, StreamExt, TryStreamExt};

async fn demo<S>(stream: S) -> Result<Vec<Output>>
where
    S: Stream<Item = Input>,
{
    stream
        .then(ffi::do_some_work) // returns Result<Output, &str>
        .map_err(Error::msg)
        .try_collect()
        .await
}

fn from_boxed(boxed_error: Box<dyn StdError + Send + Sync + 'static>) -> Self

Construct an error object from a type-erased standard library error.

This is mostly useful for interop with other error libraries.

Example

Here is a skeleton of a library that provides its own error abstraction. The pair of From impls provide bidirectional support for ? conversion between Report and anyhow::Error.

use std::error::Error as StdError;

pub struct Report {/* ... */}

impl<E> From<E> for Report
where
    E: Into<anyhow::Error>,
    Result<(), E>: anyhow::Context<(), E>,
{
    fn from(error: E) -> Self {
        let anyhow_error: anyhow::Error = error.into();
        let boxed_error: Box<dyn StdError + Send + Sync + 'static> = anyhow_error.into();
        Report::from_boxed(boxed_error)
    }
}

impl From<Report> for anyhow::Error {
    fn from(report: Report) -> Self {
        let boxed_error: Box<dyn StdError + Send + Sync + 'static> = report.into_boxed();
        anyhow::Error::from_boxed(boxed_error)
    }
}

impl Report {
    fn from_boxed(boxed_error: Box<dyn StdError + Send + Sync + 'static>) -> Self {
        todo!()
    }
    fn into_boxed(self) -> Box<dyn StdError + Send + Sync + 'static> {
        todo!()
    }
}

// Example usage: can use `?` in both directions.
fn a() -> anyhow::Result<()> {
    b()?;
    Ok(())
}
fn b() -> Result<(), Report> {
    a()?;
    Ok(())
}

fn context<C>(self, context: C) -> Self
where
    C: Display + Send + Sync + 'static,

Wrap the error value with additional context.

For attaching context to a Result as it is propagated, the [Context][crate::Context] extension trait may be more convenient than this function.

The primary reason to use error.context(...) instead of result.context(...) via the Context trait would be if the context needs to depend on some data held by the underlying error:

# use std::fmt::{self, Debug, Display};
#
# type T = ();
#
# impl std::error::Error for ParseError {}
# impl Debug for ParseError {
#     fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
#         unimplemented!()
#     }
# }
# impl Display for ParseError {
#     fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
#         unimplemented!()
#     }
# }
#
use anyhow::Result;
use std::fs::File;
use std::path::Path;

struct ParseError {
    line: usize,
    column: usize,
}

fn parse_impl(file: File) -> Result<T, ParseError> {
    # const IGNORE: &str = stringify! {
    ...
    # };
    # unimplemented!()
}

pub fn parse(path: impl AsRef<Path>) -> Result<T> {
    let file = File::open(&path)?;
    parse_impl(file).map_err(|error| {
        let context = format!(
            "only the first {} lines of {} are valid",
            error.line, path.as_ref().display(),
        );
        anyhow::Error::new(error).context(context)
    })
}

fn backtrace(&self) -> &Backtrace

Get the backtrace for this Error.

In order for the backtrace to be meaningful, one of the two environment variables RUST_LIB_BACKTRACE=1 or RUST_BACKTRACE=1 must be defined and RUST_LIB_BACKTRACE must not be 0. Backtraces are somewhat expensive to capture in Rust, so we don't necessarily want to be capturing them all over the place all the time.

• If you want panics and errors to both have backtraces, set RUST_BACKTRACE=1;
• If you want only errors to have backtraces, set RUST_LIB_BACKTRACE=1;
• If you want only panics to have backtraces, set RUST_BACKTRACE=1 and RUST_LIB_BACKTRACE=0.

Stability

Standard library backtraces are only available when using Rust ≥ 1.65. On older compilers, this function is only available if the crate's "backtrace" feature is enabled, and will use the backtrace crate as the underlying backtrace implementation. The return type of this function on old compilers is &(impl Debug + Display).

[dependencies]
anyhow = { version = "1.0", features = ["backtrace"] }

fn chain(&self) -> Chain<'_>

An iterator of the chain of source errors contained by this Error.

This iterator will visit every error in the cause chain of this error object, beginning with the error that this error object was created from.

Example

use anyhow::Error;
use std::io;

pub fn underlying_io_error_kind(error: &Error) -> Option<io::ErrorKind> {
    for cause in error.chain() {
        if let Some(io_error) = cause.downcast_ref::<io::Error>() {
            return Some(io_error.kind());
        }
    }
    None
}

fn root_cause(&self) -> &dyn StdError + 'static

The lowest level cause of this error — this error's cause's cause's cause etc.

The root cause is the last error in the iterator produced by [chain()][Error::chain].

fn is<E>(&self) -> bool
where
    E: Display + Debug + Send + Sync + 'static,

Returns true if E is the type held by this error object.

For errors with context, this method returns true if E matches the type of the context C or the type of the error on which the context has been attached. For details about the interaction between context and downcasting, see here.

fn downcast<E>(self) -> Result<E, Self>
where
    E: Display + Debug + Send + Sync + 'static,

Attempt to downcast the error object to a concrete type.

fn downcast_ref<E>(&self) -> Option<&E>
where
    E: Display + Debug + Send + Sync + 'static,

Downcast this error object by reference.

Example

# use anyhow::anyhow;
# use std::fmt::{self, Display};
# use std::task::Poll;
#
# #[derive(Debug)]
# enum DataStoreError {
#     Censored(()),
# }
#
# impl Display for DataStoreError {
#     fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
#         unimplemented!()
#     }
# }
#
# impl std::error::Error for DataStoreError {}
#
# const REDACTED_CONTENT: () = ();
#
# let error = anyhow!("...");
# let root_cause = &error;
#
# let ret =
// 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),
}
# ;

fn downcast_mut<E>(&mut self) -> Option<&mut E>
where
    E: Display + Debug + Send + Sync + 'static,

Downcast this error object by mutable reference.

fn into_boxed_dyn_error(self) -> Box<dyn StdError + Send + Sync + 'static>

Convert to a standard library error trait object.

This is implemented as a cheap pointer cast that does not allocate or deallocate memory. Like anyhow::Error::from_boxed, it's useful for interop with other error libraries.

The same conversion is also available as impl From<anyhow::Error> for Box<dyn Error + Send + Sync + 'static>.

If a backtrace was collected during construction of the anyhow::Error, that backtrace remains accessible using the standard library Error trait's provider API, but as a consequence, the resulting boxed error can no longer be downcast to its original underlying type.

#![feature(error_generic_member_access)]

use anyhow::anyhow;
use std::backtrace::Backtrace;
use thiserror::Error;

#[derive(Error, Debug)]
#[error("...")]
struct MyError;

let anyhow_error = anyhow!(MyError);
println!("{}", anyhow_error.backtrace());  // has Backtrace
assert!(anyhow_error.downcast_ref::<MyError>().is_some());  // can downcast

let boxed_dyn_error = anyhow_error.into_boxed_dyn_error();
assert!(std::error::request_ref::<Backtrace>(&*boxed_dyn_error).is_some());  // has Backtrace
assert!(boxed_dyn_error.downcast_ref::<MyError>().is_none());  // can no longer downcast

fn reallocate_into_boxed_dyn_error_without_backtrace(self) -> Box<dyn StdError + Send + Sync + 'static>

Convert to a standard library error trait object.

Unlike self.into_boxed_dyn_error(), this method relocates the underlying error into a new allocation in order to make it downcastable to &E or Box<E> for its original underlying error type. Any backtrace collected during construction of the anyhow::Error is discarded.

#![feature(error_generic_member_access)]

use anyhow::anyhow;
use std::backtrace::Backtrace;
use thiserror::Error;

#[derive(Error, Debug)]
#[error("...")]
struct MyError;

let anyhow_error = anyhow!(MyError);
println!("{}", anyhow_error.backtrace());  // has Backtrace
assert!(anyhow_error.downcast_ref::<MyError>().is_some());  // can downcast

let boxed_dyn_error = anyhow_error.reallocate_into_boxed_dyn_error_without_backtrace();
assert!(std::error::request_ref::<Backtrace>(&*boxed_dyn_error).is_none());  // Backtrace lost
assert!(boxed_dyn_error.downcast_ref::<MyError>().is_some());  // can downcast to &MyError
assert!(boxed_dyn_error.downcast::<MyError>().is_ok());  // can downcast to Box<MyError>