Struct Report 

pub struct Report<C>
where
    C: ?Sized,
{ /* private fields */ }

Contains a [Frame] stack consisting of Error contexts and attachments.

Attachments can be added by using attach_opaque(). The [Frame] stack can be iterated by using frames().

When creating a Report by using new(), the passed Error context is used to set the current context on the Report. To provide a new one, use change_context().

Attachments, and objects provided by a Error context, are directly retrievable by calling request_ref() or request_value().

Formatting

Report implements Display and Debug. When utilizing the Display implementation, the current context of the Report is printed, e.g. println!("{report}"). For the alternate Display output ("{:#}"), all Error contexts are printed. To print the full stack of Error contexts and attachments, use the Debug implementation ("{:?}"). To customize the output of the attachments in the Debug output, please see the error_stack::fmt module.

Please see the examples below for more information.

Multiple Errors

Report comes in two variants: Report<C> which represents a single error context, and Report<[C]> which can represent multiple error contexts. To combine multiple errors, first convert a Report<C> to Report<[C]> using expand(), then use push() to add additional errors. This allows for representing complex error scenarios with multiple related simultaneous errors.

Backtrace and SpanTrace

Report is able to provide a Backtrace and a [SpanTrace], which can be retrieved by calling request_ref::<Backtrace>() or request_ref::<SpanTrace>() (downcast_ref::<SpanTrace>() on stable) respectively. If the root context provides a Backtrace or a [SpanTrace], those are returned, otherwise, if configured, an attempt is made to capture them when creating a Report. To enable capturing of the backtrace, make sure RUST_BACKTRACE or RUST_LIB_BACKTRACE is set according to the Backtrace documentation. To enable capturing of the span trace, an ErrorLayer has to be enabled. Please also see the Feature Flags section. A single Report can have multiple Backtraces and [SpanTrace]s, depending on the amount of related errors the Report consists of. Therefore it isn’t guaranteed that request_ref() will only ever return a single Backtrace or [SpanTrace].

Examples

Provide a context for an error

use error_stack::ResultExt;

let config_path = "./path/to/config.file";
let content = std::fs::read_to_string(config_path)
    .attach_with(|| format!("failed to read config file {config_path:?}"))?;

...

Enforce a context for an error

use std::{error::Error, fmt, path::{Path, PathBuf}};

use error_stack::{Report, ResultExt};

#[derive(Debug)]
enum RuntimeError {
    InvalidConfig(PathBuf),
    ...
}

#[derive(Debug)]
enum ConfigError {
    IoError,
    ...
}

impl fmt::Display for RuntimeError {
    ...
}
impl fmt::Display for ConfigError {
    ...
}

impl Error for RuntimeError {}
impl Error for ConfigError {}

fn read_config(path: impl AsRef<Path>) -> Result<String, Report<ConfigError>> {
    std::fs::read_to_string(path.as_ref()).change_context(ConfigError::IoError)
}

fn main() -> Result<(), Report<RuntimeError>> {
    let config_path = "./path/to/config.file";
    let config = read_config(config_path)
            .change_context_lazy(|| RuntimeError::InvalidConfig(PathBuf::from(config_path)))?;

    ...
}

Formatting

For the example from above, the report could be formatted as follows:

If the Display implementation of Report will be invoked, this will print something like:

If the alternate Display implementation of Report is invoked ({report:#}), this will print something like:

The Debug implementation of Report will print something like:

Get the attached Backtrace and [SpanTrace]:

use error_stack::{ResultExt, Report};

let config_path = "./path/to/config.file";
let content = std::fs::read_to_string(config_path)
    .attach_with(|| format!("failed to read config file {config_path:?}"));

let content = match content {
    Err(err) => {
        for backtrace in err.request_ref::<std::backtrace::Backtrace>() {
            println!("backtrace: {backtrace}");
        }

        for span_trace in err.request_ref::<tracing_error::SpanTrace>() {
            println!("span trace: {span_trace}")
        }

        return Err(err)
    }

    Ok(ok) => ok
};

...

Implementations

impl<C> Report<C>

pub fn new(context: C) -> Report<C>

where C: Error + Send + Sync + 'static,

Creates a new Report<Context> from a provided scope.

If context does not provide Backtrace/[SpanTrace] then this attempts to capture them directly. Please see the Backtrace and SpanTrace section of the Report documentation for more information.

pub fn expand(self) -> Report<[C]>

Converts a Report with a single context into a Report with multiple contexts.

This function allows for the transformation of a Report<C> into a Report<[C]>, enabling the report to potentially hold multiple current contexts of the same type.

Example

use error_stack::Report;

#[derive(Debug)]
struct SystemFailure;

impl std::fmt::Display for SystemFailure {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str("System failure occured")
    }
}

impl core::error::Error for SystemFailure {}

// Type annotations are used here to illustrate the types used, these are not required
let failure: Report<SystemFailure> = Report::new(SystemFailure);
let mut failures: Report<[SystemFailure]> = failure.expand();

assert_eq!(failures.current_frames().len(), 1);

let another_failure = Report::new(SystemFailure);
failures.push(another_failure);

assert_eq!(failures.current_frames().len(), 2);

pub fn current_frame(&self) -> &Frame

Returns the direct current frames of this report.

To get an iterator over the topological sorting of all frames refer to frames().

This is not the same as Report::current_context, this function gets the underlying frames that make up this report, while Report::current_context traverses the stack of frames to find the current context. A Report and be made up of multiple [Frame]s, which stack on top of each other. Considering PrintableA<PrintableA<Context>>, Report::current_frame will return the “outer” layer PrintableA, while Report::current_context will return the underlying Error (the current type parameter of this Report).

A report can be made up of multiple stacks of frames and builds a “group” of them, this can be achieved through first calling Report::expand and then either using Extend or Report::push.

pub fn current_context(&self) -> &C

where C: Send + Sync + 'static,

Returns the current context of the Report.

If the user want to get the latest context, current_context can be called. If the user wants to handle the error, the context can then be used to directly access the context’s type. This is only possible for the latest context as the Report does not have multiple generics as this would either require variadic generics or a workaround like tuple-list.

This is one disadvantage of the library in comparison to plain Errors, as in these cases, all context types are known.

Example

use std::io;

fn read_file(path: impl AsRef<Path>) -> Result<String, Report<io::Error>> {
    ...
}

let report = read_file("test.txt").unwrap_err();
let io_error = report.current_context();
assert_eq!(io_error.kind(), io::ErrorKind::NotFound);

pub fn into_error(self) -> impl Error + Send + Sync + 'static

where C: 'static,

Converts this Report to an Error.

pub fn as_error(&self) -> &(impl Error + Send + Sync + 'static)

where C: 'static,

Returns this Report as an Error.

impl<C> Report<C>

where C: ?Sized,

pub fn attach<A>(self, attachment: A) -> Report<C>

where A: Attachment,

Adds additional (printable) information to the [Frame] stack.

This behaves like attach_opaque() but the display implementation will be called when printing the Report.

Note: attach_opaque() will be deprecated when specialization is stabilized and it becomes possible to merge these two methods.

Example

use core::fmt;
use std::fs;

use error_stack::ResultExt;

#[derive(Debug)]
pub struct Suggestion(&'static str);

impl fmt::Display for Suggestion {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.write_str(self.0)
    }
}

let error = fs::read_to_string("config.txt")
    .attach(Suggestion("better use a file which exists next time!"));
let report = error.unwrap_err();
let suggestion = report.request_ref::<Suggestion>().next().unwrap();

assert_eq!(suggestion.0, "better use a file which exists next time!");

pub fn attach_opaque<A>(self, attachment: A) -> Report<C>

where A: OpaqueAttachment,

Adds additional information to the [Frame] stack.

This behaves like attach() but will not be shown when printing the Report. To benefit from seeing attachments in normal error outputs, use attach().

Note: This will be deprecated in favor of attach() when specialization is stabilized it becomes possible to merge these two methods.

pub fn change_context<T>(self, context: T) -> Report<T>

where T: Error + Send + Sync + 'static,

Add a new Error object to the top of the [Frame] stack, changing the type of the Report.

Please see the Error documentation for more information.

pub fn frames(&self) -> Frames<'_>

Returns an iterator over the [Frame] stack of the report.

pub fn frames_mut( &mut self, visitor: impl FnMut(&mut Frame) -> ControlFlow<()>, ) -> ControlFlow<()>

Visits every [Frame] of the report mutably, in the same order as frames().

Returning ControlFlow::Break from visitor stops the traversal early. The break is propagated to the caller, a full traversal returns ControlFlow::Continue.

This is deliberately not an Iterator: an iterator over &mut Frame hands out references whose lifetimes are independent of each other, so a frame and one of its sources (reachable via [Frame::sources_mut]) could be borrowed mutably at the same time. Scoping mutable access to a visitor rules that out.

Example

let mut report = read_file("test.txt").unwrap_err();
let flow = report.frames_mut(|frame| {
    if let Some(io_error) = frame.downcast_mut::<io::Error>() {
        *io_error = io::Error::from(io::ErrorKind::Other);
        return ControlFlow::Break(());
    }
    ControlFlow::Continue(())
});
assert!(flow.is_break());

pub fn contains<T>(&self) -> bool

where T: Send + Sync + 'static,

Returns if T is the type held by any frame inside of the report.

T could either be an attachment or a Error context.

Example

fn read_file(path: impl AsRef<Path>) -> Result<String, Report<io::Error>> {
    ...
}

let report = read_file("test.txt").unwrap_err();
assert!(report.contains::<io::Error>());

pub fn downcast_ref<T>(&self) -> Option<&T>

where T: Send + Sync + 'static,

Searches the frame stack for a context provider T and returns the most recent context found.

T can either be an attachment or a new Error context.

Example

use std::io;

fn read_file(path: impl AsRef<Path>) -> Result<String, Report<io::Error>> {
    ...
}

let report = read_file("test.txt").unwrap_err();
let io_error = report.downcast_ref::<io::Error>().unwrap();
assert_eq!(io_error.kind(), io::ErrorKind::NotFound);

pub fn downcast_mut<T>(&mut self) -> Option<&mut T>

where T: Send + Sync + 'static,

Searches the frame stack for an instance of type T, returning the most recent one found.

T can either be an attachment or a new Error context.

impl<C> Report<[C]>

pub fn current_frames(&self) -> &[Frame]

Returns the direct current frames of this report.

To get an iterator over the topological sorting of all frames refer to frames().

This is not the same as Report::current_context, this function gets the underlying frames that make up this report, while Report::current_context traverses the stack of frames to find the current context. A Report and be made up of multiple [Frame]s, which stack on top of each other. Considering PrintableA<PrintableA<Context>>, Report::current_frames will return the “outer” layer PrintableA, while Report::current_context will return the underlying Error (the current type parameter of this Report).

Using Extend, push() and append(), a Report can additionally be made up of multiple stacks of frames and builds a “group” of them, therefore this function returns a slice instead, while Report::current_context only returns a single reference.

pub fn push(&mut self, report: Report<C>)

Pushes a new context to the Report.

This function adds a new [Frame] to the current frames with the frame from the given Report.

Example

use std::{fmt, path::Path};

use error_stack::{Report, ResultExt};

#[derive(Debug)]
struct IoError;

impl fmt::Display for IoError {
            ...
}


fn read_config(path: impl AsRef<Path>) -> Result<String, Report<IoError>> {
    std::fs::read_to_string(path.as_ref())
        .change_context(IoError)
}

let mut error1 = read_config("config.txt").unwrap_err().expand();
let error2 = read_config("config2.txt").unwrap_err();
let error3 = read_config("config3.txt").unwrap_err();

error1.push(error2);
error1.push(error3);

pub fn append(&mut self, report: Report<[C]>)

Appends the frames from another Report to this one.

This method combines the frames of the current Report with those of the provided Report, effectively merging the two error reports.

Example

use std::{fmt, path::Path};

use error_stack::{Report, ResultExt};

#[derive(Debug)]
struct IoError;

impl fmt::Display for IoError {
            ...
}


fn read_config(path: impl AsRef<Path>) -> Result<String, Report<IoError>> {
    std::fs::read_to_string(path.as_ref())
        .change_context(IoError)
}

let mut error1 = read_config("config.txt").unwrap_err().expand();
let error2 = read_config("config2.txt").unwrap_err();
let mut error3 = read_config("config3.txt").unwrap_err().expand();

error1.push(error2);
error3.append(error1);

pub fn current_contexts(&self) -> impl Iterator<Item = &C>

where C: Send + Sync + 'static,

Returns an iterator over the current contexts of the Report.

This method is similar to current_context, but instead of returning a single context, it returns an iterator over all contexts in the Report.

The order of the contexts should not be relied upon, as it is not guaranteed to be stable.

Example

use std::io;

fn read_file(path: impl AsRef<Path>) -> Result<String, Report<io::Error>> {
    ...
}

let mut a = read_file("test.txt").unwrap_err().expand();
let b = read_file("test2.txt").unwrap_err();

a.push(b);

let io_error = a.current_contexts();
assert_eq!(io_error.count(), 2);

impl Report<()>

pub fn set_charset(charset: Charset)

Sets the charset preference.

The value defaults to [Charset::Utf8].

Example

use std::io::{Error, ErrorKind};

use error_stack::{Report, IntoReport};
use error_stack::fmt::{Charset};

struct Suggestion(&'static str);

Report::install_debug_hook::<Suggestion>(|Suggestion(value), context| {
    match context.charset() {
        Charset::Utf8 => context.push_body(format!("📝 {value}")),
        Charset::Ascii => context.push_body(format!("suggestion: {value}"))
    };
});

let report =
    Error::from(ErrorKind::InvalidInput).into_report().attach_opaque(Suggestion("oh no, try again"));

Report::set_charset(Charset::Utf8);
println!("{report:?}");

Report::set_charset(Charset::Ascii);
println!("{report:?}");

Which will result in something like:

impl Report<()>

pub fn set_color_mode(mode: ColorMode)

Sets the color mode preference.

If no [ColorMode] is set, it defaults to [ColorMode::Emphasis].

Example

use std::io::{Error, ErrorKind};
use owo_colors::OwoColorize;

use error_stack::{Report, IntoReport};
use error_stack::fmt::ColorMode;

struct Suggestion(&'static str);

Report::install_debug_hook::<Suggestion>(|Suggestion(value), context| {
    let body = format!("suggestion: {value}");
    match context.color_mode() {
        ColorMode::Color => context.push_body(body.green().to_string()),
        ColorMode::Emphasis => context.push_body(body.italic().to_string()),
        ColorMode::None => context.push_body(body)
    };
});

let report =
    Error::from(ErrorKind::InvalidInput).into_report().attach_opaque(Suggestion("oh no, try again"));

Report::set_color_mode(ColorMode::None);
println!("{report:?}");

Report::set_color_mode(ColorMode::Emphasis);
println!("{report:?}");

Report::set_color_mode(ColorMode::Color);
println!("{report:?}");

Which will result in something like:

impl Report<()>

pub fn install_debug_hook<T>( hook: impl Fn(&T, &mut HookContext<T>) + Send + Sync + 'static, )

where T: Send + Sync + 'static,

Can be used to globally set a Debug format hook, for a specific type T.

This hook will be called on every Debug call, if an attachment with the same type has been found.

Examples

use std::io::{Error, ErrorKind};

use error_stack::{
    Report, IntoReport,
};

struct Suggestion(&'static str);

Report::install_debug_hook::<Suggestion>(|value, context| {
    context.push_body(format!("suggestion: {}", value.0));
});

let report =
    Error::from(ErrorKind::InvalidInput).into_report().attach_opaque(Suggestion("oh no, try again"));

println!("{report:?}");

Which will result in something like:

This example showcases the ability of hooks to be invoked for values provided via the Provider API using Error::provide.

#![feature(error_generic_member_access)]

use core::error::{Request, Error};
use core::fmt;
use error_stack::{Report, IntoReport};

struct Suggestion(&'static str);

#[derive(Debug)]
struct ErrorCode(u64);


#[derive(Debug)]
struct UserError {
    code: ErrorCode
}

impl fmt::Display for UserError {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.write_str("invalid user input")
    }
}

impl Error for UserError {
 fn provide<'a>(&'a self, req: &mut Request<'a>) {
   req.provide_value(Suggestion("try better next time!"));
   req.provide_ref(&self.code);
 }
}

Report::install_debug_hook::<Suggestion>(|Suggestion(value), context| {
    context.push_body(format!("suggestion: {value}"));
});
Report::install_debug_hook::<ErrorCode>(|ErrorCode(value), context| {
    context.push_body(format!("error code: {value}"));
});

let report = UserError {code: ErrorCode(420)}.into_report();

println!("{report:?}");

Which will result in something like:

error-stack comes with some built-in hooks which can be overwritten. This is useful if you want to change the output of the built-in hooks, or if you want to add additional information to the output. For example, you can override the built-in hook for Location to hide the file path:

use std::{
    io::{Error, ErrorKind},
    panic::Location,
};

use error_stack::IntoReport;

error_stack::Report::install_debug_hook::<Location>(|_location, _context| {
    // Intentionally left empty so nothing will be printed
});

let report = Error::from(ErrorKind::InvalidInput).into_report();

println!("{report:?}");

Which will result in something like:

Trait Implementations

impl<C> Debug for Report<C>

where C: ?Sized,

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

Formats the value using the given formatter.

impl<C> Display for Report<C>

where C: ?Sized,

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

Formats the value using the given formatter.

impl<C> Extend<Report<[C]>> for Report<[C]>

fn extend<T>(&mut self, iter: T)

where T: IntoIterator<Item = Report<[C]>>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<C> Extend<Report<C>> for Report<[C]>

fn extend<T>(&mut self, iter: T)

where T: IntoIterator<Item = Report<C>>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<C> From<C> for Report<C>

where C: Error + Send + Sync + 'static,

fn from(context: C) -> Report<C>

Converts to this type from the input type.

impl<C> From<Report<C>> for Report<[C]>

fn from(report: Report<C>) -> Report<[C]>

Converts to this type from the input type.

impl<C> FromIterator<Report<[C]>> for Option<Report<[C]>>

fn from_iter<T>(iter: T) -> Option<Report<[C]>>

where T: IntoIterator<Item = Report<[C]>>,

Creates a value from an iterator.

impl<C> FromIterator<Report<C>> for Option<Report<[C]>>

fn from_iter<T>(iter: T) -> Option<Report<[C]>>

where T: IntoIterator<Item = Report<C>>,

Creates a value from an iterator.

impl<C> IntoReport for Report<C>

where C: ?Sized,

type Context = C

The context type that will be used in the resulting Report.

fn into_report(self) -> Report<<Report<C> as IntoReport>::Context>

Converts this value into a Report.

impl<C> Termination for Report<C>

Available on crate feature std only.

fn report(self) -> ExitCode

Is called to get the representation of the value as status code. This status code is returned to the operating system.