Struct anyhow::Error

source · [−]
#[repr(transparent)]
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

Available on crate feature std only.

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.

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
}

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)
    })
}
Available on nightly or crate feature backtrace only.

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 on the nightly channel. Tracking issue: rust-lang/rust#53487.

On stable 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.

[dependencies]
anyhow = { version = "1.0", features = ["backtrace"] }
Available on crate feature std only.

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
}
Available on crate feature std only.

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().

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.

Attempt to downcast the error object to a concrete type.

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

Downcast this error object by mutable reference.

Trait Implementations

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

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

Formats the value using the given formatter. Read more

The resulting type after dereferencing.

Dereferences the value.

Mutably dereferences the value.

Formats the value using the given formatter. Read more

Executes the destructor for this type. Read more

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Converts to this type from the input type.

Returns the argument unchanged.

Calls U::from(self).

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

Converts the given value to a String. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.