## Error

# Struct Error

Source

    pub struct Error { /* private fields */ }

Expand description

The `Error` type, a wrapper around a dynamic error type.

`Error` works a lot like `Box<dyn std::error::Error>`, but with these differences:

- `Error` requires that the error is `Send`, `Sync`, and `'static`.
- `Error` guarantees that a backtrace is available, even if the underlying error type does not provide one.
- `Error` is represented as a narrow pointer — exactly one word in size instead of two.

## §Display representations

When you print an error object using “{}” or to_string(), only the outermost underlying error or context is printed, not any of the lower level causes. This is exactly as if you had called the Display impl of the error from which you constructed your anyhow::Error.

    Failed to read instrs from ./path/to/instrs.json

To print causes as well using anyhow’s default formatting of causes, use the alternate selector “{:#}”.

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

The Debug format “{:?}” includes your backtrace if one was captured. Note that this is the representation you get by default if you return an error from `fn main` instead of printing it explicitly yourself.

    Error: Failed to read instrs from ./path/to/instrs.json

    Caused by:
        No such file or directory (os error 2)

and if there is a backtrace available:

    Error: Failed to read instrs from ./path/to/instrs.json

    Caused by:
        No such file or directory (os error 2)

    Stack backtrace:
       0: <E as anyhow::context::ext::StdError>::ext_context
                 at /git/anyhow/src/backtrace.rs:26
       1: core::result::Result<T,E>::map_err
                 at /git/rustc/src/libcore/result.rs:596
       2: anyhow::context::<impl anyhow::Context<T,E> for core::result::Result<T,E>>::with_context
                 at /git/anyhow/src/context.rs:58
       3: testing::main
                 at src/main.rs:5
       4: std::rt::lang_start
                 at /git/rustc/src/libstd/rt.rs:61
       5: main
       6: __libc_start_main
       7: _start

To see a conventional struct-style Debug representation, use “{:#?}”.

    Error {
        context: "Failed to read instrs from ./path/to/instrs.json",
        source: Os {
            code: 2,
            kind: NotFound,
            message: "No such file or directory",
        },
    }

If none of the built-in representations are appropriate and you would prefer to render the error and its cause chain yourself, it can be done something like this:

    use anyhow::{Context, Result};

    fn main() {
        if let Err(err) = try_main() {
            eprintln!("ERROR: {}", err);
            err.chain().skip(1).for_each(|cause| eprintln!("because: {}", cause));
            std::process::exit(1);
        }
    }

    fn try_main() -> Result<()> {
        ...
    }

## Implementations§

Source§

### impl Error

Source

#### pub 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.

Source

#### pub 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:

    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
    }

Source

#### pub 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(())
    }

Source

#### pub 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` 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 anyhow::Result;
    use std::fs::File;
    use std::path::Path;

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

    fn parse_impl(file: File) -> Result<T, ParseError> {
        ...
    }

    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)
        })
    }

Source

#### pub 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"] }

Source

#### pub 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
    }

Source

#### pub 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()`.

Source

#### pub 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.

Source

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

Attempt to downcast the error object to a concrete type.

Source

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

Downcast this error object by reference.

##### §Example

    // 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),
    }

Source

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

Downcast this error object by mutable reference.

Source

#### pub 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

Source

#### pub 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>

## Trait Implementations§

Source§

### impl AsRef<dyn Error> for Error

Source§

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

Converts this type into a shared reference of the (usually inferred) input type.
Source§

### impl AsRef<dyn Error + Sync + Send> for Error

Source§

#### fn as_ref(&self) -> &(dyn StdError + Send + Sync + 'static)

Converts this type into a shared reference of the (usually inferred) input type.
Source§

### impl Debug for Error

Source§

#### fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

### impl Deref for Error

Source§

#### type Target = dyn Error + Sync + Send

The resulting type after dereferencing.
Source§

#### fn deref(&self) -> &Self::Target

Dereferences the value.
Source§

### impl DerefMut for Error

Source§

#### fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.
Source§

### impl Display for Error

Source§

#### fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

### impl Drop for Error

Source§

#### fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

### impl<E> From<E> for Error
where E: StdError + Send + Sync + 'static,

Source§

#### fn from(error: E) -> Self

Converts to this type from the input type.
Source§

### impl From<Error> for Box<dyn StdError + 'static>

Source§

#### fn from(error: Error) -> Self

Converts to this type from the input type.
Source§

### impl From<Error> for Box<dyn StdError + Send + 'static>

Source§

#### fn from(error: Error) -> Self

Converts to this type from the input type.
Source§

### impl From<Error> for Box<dyn StdError + Send + Sync + 'static>

Source§

#### fn from(error: Error) -> Self

Converts to this type from the input type.
Source§

### impl RefUnwindSafe for Error

Source§

### impl UnwindSafe for Error

## Auto Trait Implementations§

§

### impl Freeze for Error

§

### impl Send for Error

§

### impl Sync for Error

§

### impl Unpin for Error

## Blanket Implementations§

Source§

### impl<T> Any for T
where T: 'static + ?Sized,

Source§

#### fn type_id(&self) -> TypeId

Gets the `TypeId` of `self`. Read more
Source§

### impl<T> Borrow<T> for T
where T: ?Sized,

Source§

#### fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

### impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

#### fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

### impl<T> From<!> for T

Source§

#### fn from(t: !) -> T

Converts to this type from the input type.
Source§

### impl<T> From<T> for T

Source§

#### fn from(t: T) -> T

Returns the argument unchanged.

Source§

### impl<T, U> Into<U> for T
where U: From<T>,

Source§

#### fn into(self) -> U

Calls `U::from(self)`.

That is, this conversion is whatever the implementation of `From<T> for U` chooses to do.

Source§

### impl<P, T> Receiver for P
where P: Deref<Target = T> + ?Sized, T: ?Sized,

Source§

#### type Target = T

🔬This is a nightly-only experimental API. (`arbitrary_self_types`)
The target type on which the method may be called.
Source§

### impl<T> ToString for T
where T: Display + ?Sized,

Source§

#### fn to_string(&self) -> String

Converts the given value to a `String`. Read more
Source§

### impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

#### type Error = Infallible

The type returned in the event of a conversion error.
Source§

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

### impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

#### type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.