Struct Report 

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

Contains a Frame stack consisting of 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 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 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 Contexts are printed. To print the full stack of 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 SpanTraces, 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:

could not parse "./path/to/config.file"

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

could not parse "./path/to/config.file": config file is invalid: No such file or directory (os error 2)

The Debug implementation of Report will print something like:

could not parse "./path/to/config.file"
├╴at libs/error-stack/src/report.rs:59:14
│
├─▶ config file is invalid
│   ╰╴at libs/error-stack/src/report.rs:51:44
│
╰─▶ No such file or directory (os error 2)
    ├╴at libs/error-stack/src/report.rs:51:44
    ╰╴backtrace (1)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

backtrace no. 1
  [redacted]

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

where C: Context,

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.

Examples found in repository

examples/exit_code.rs (line 20)

fn main() -> ExitCode {
    let report = Report::new(CustomError)
        .attach_opaque(ExitCode::from(100))
        .attach("this error has an exit code of 100!");

    report.report()
}

examples/detect.rs (line 38)

fn parse_config(path: impl AsRef<Path>) -> Result<Config, Report<ParseConfigError>> {
    _ = path.as_ref();

    /*
       usually you would actually do something here, we just error out, for a more complete example
       check out the other examples
    */

    Err(Report::new(ParseConfigError).attach("unable to read configuration"))
}

examples/demo.rs (line 74)

fn start_experiments(
    experiment_ids: &[usize],
    experiment_descriptions: &[&str],
) -> Result<Vec<u64>, Report<[ExperimentError]>> {
    let experiments = experiment_ids
        .iter()
        .map(|exp_id| {
            let description = experiment_descriptions.get(*exp_id).ok_or_else(|| {
                Report::new(ExperimentError)
                    .attach(format!("experiment {exp_id} has no valid description"))
            })?;

            let experiments = parse_experiment(description)
                .attach(format!("experiment {exp_id} could not be parsed"))
                .change_context(ExperimentError)?;

            let experiments = experiments
                .into_iter()
                .map(|(lhs, rhs)| move || lhs * rhs)
                .collect::<Vec<_>>();

            Ok(experiments)
        })
        .fold(
            Ok(vec![]),
            |accum, value: Result<_, Report<ExperimentError>>| match (accum, value) {
                (Ok(mut accum), Ok(value)) => {
                    accum.extend(value);

                    Ok(accum)
                }
                (Ok(_), Err(err)) => Err(err.expand()),
                (Err(accum), Ok(_)) => Err(accum),
                (Err(mut accum), Err(err)) => {
                    accum.push(err);

                    Err(accum)
                }
            },
        )
        .attach("unable to set up experiments")?;

    Ok(experiments.iter().map(|experiment| experiment()).collect())
}

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

Examples found in repository

examples/demo.rs (line 38)

fn parse_experiment(description: &str) -> Result<Vec<(u64, u64)>, Report<ParseExperimentError>> {
    let values = description
        .split(' ')
        .map(|value| {
            value
                .parse::<u64>()
                .attach_with(|| format!("{value:?} could not be parsed as experiment"))
        })
        .map(|value| value.map(|ok| (ok, 2 * ok)))
        .fold(Ok(vec![]), |accum, value| match (accum, value) {
            (Ok(mut accum), Ok(value)) => {
                accum.push(value);

                Ok(accum)
            }
            (Ok(_), Err(err)) => Err(err.expand()),
            (Err(accum), Ok(_)) => Err(accum),
            (Err(mut accum), Err(err)) => {
                accum.push(err);

                Err(accum)
            }
        })
        .change_context(ParseExperimentError)?;

    Ok(values)
}

#[derive(Debug)]
struct ExperimentError;

impl fmt::Display for ExperimentError {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.write_str("experiment error: could not run experiment")
    }
}

impl Error for ExperimentError {}

#[expect(
    clippy::manual_try_fold,
    reason = "false-positive, try_fold is fail-fast, our implementation is fail-slow"
)]
fn start_experiments(
    experiment_ids: &[usize],
    experiment_descriptions: &[&str],
) -> Result<Vec<u64>, Report<[ExperimentError]>> {
    let experiments = experiment_ids
        .iter()
        .map(|exp_id| {
            let description = experiment_descriptions.get(*exp_id).ok_or_else(|| {
                Report::new(ExperimentError)
                    .attach(format!("experiment {exp_id} has no valid description"))
            })?;

            let experiments = parse_experiment(description)
                .attach(format!("experiment {exp_id} could not be parsed"))
                .change_context(ExperimentError)?;

            let experiments = experiments
                .into_iter()
                .map(|(lhs, rhs)| move || lhs * rhs)
                .collect::<Vec<_>>();

            Ok(experiments)
        })
        .fold(
            Ok(vec![]),
            |accum, value: Result<_, Report<ExperimentError>>| match (accum, value) {
                (Ok(mut accum), Ok(value)) => {
                    accum.extend(value);

                    Ok(accum)
                }
                (Ok(_), Err(err)) => Err(err.expand()),
                (Err(accum), Ok(_)) => Err(accum),
                (Err(mut accum), Err(err)) => {
                    accum.push(err);

                    Err(accum)
                }
            },
        )
        .attach("unable to set up experiments")?;

    Ok(experiments.iter().map(|experiment| experiment()).collect())
}

pub fn current_frame(&self) -> &Frame

Return 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 Frames, 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: ?Sized> Report<C>

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

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!");

Examples found in repository

examples/exit_code.rs (line 22)

fn main() -> ExitCode {
    let report = Report::new(CustomError)
        .attach_opaque(ExitCode::from(100))
        .attach("this error has an exit code of 100!");

    report.report()
}

examples/detect.rs (line 38)

fn parse_config(path: impl AsRef<Path>) -> Result<Config, Report<ParseConfigError>> {
    _ = path.as_ref();

    /*
       usually you would actually do something here, we just error out, for a more complete example
       check out the other examples
    */

    Err(Report::new(ParseConfigError).attach("unable to read configuration"))
}

examples/demo.rs (line 75)

fn start_experiments(
    experiment_ids: &[usize],
    experiment_descriptions: &[&str],
) -> Result<Vec<u64>, Report<[ExperimentError]>> {
    let experiments = experiment_ids
        .iter()
        .map(|exp_id| {
            let description = experiment_descriptions.get(*exp_id).ok_or_else(|| {
                Report::new(ExperimentError)
                    .attach(format!("experiment {exp_id} has no valid description"))
            })?;

            let experiments = parse_experiment(description)
                .attach(format!("experiment {exp_id} could not be parsed"))
                .change_context(ExperimentError)?;

            let experiments = experiments
                .into_iter()
                .map(|(lhs, rhs)| move || lhs * rhs)
                .collect::<Vec<_>>();

            Ok(experiments)
        })
        .fold(
            Ok(vec![]),
            |accum, value: Result<_, Report<ExperimentError>>| match (accum, value) {
                (Ok(mut accum), Ok(value)) => {
                    accum.extend(value);

                    Ok(accum)
                }
                (Ok(_), Err(err)) => Err(err.expand()),
                (Err(accum), Ok(_)) => Err(accum),
                (Err(mut accum), Err(err)) => {
                    accum.push(err);

                    Err(accum)
                }
            },
        )
        .attach("unable to set up experiments")?;

    Ok(experiments.iter().map(|experiment| experiment()).collect())
}

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

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.

Examples found in repository

examples/exit_code.rs (line 21)

fn main() -> ExitCode {
    let report = Report::new(CustomError)
        .attach_opaque(ExitCode::from(100))
        .attach("this error has an exit code of 100!");

    report.report()
}

pub fn attach_printable<A>(self, attachment: A) -> Self

where A: Attachment,

👎Deprecated since 0.6.0: Use attach instead. attach was renamed to attach_opaque and attach_printable was renamed to attach

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

where T: Context,

Add a new Context object to the top of the Frame stack, changing the type of the Report.

Please see the Context 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) -> FramesMut<'_>

Returns an iterator over the Frame stack of the report with mutable elements.

pub fn request_ref<T: ?Sized + Send + Sync + 'static>( &self, ) -> RequestRef<'_, T>

Available on nightly only.

Creates an iterator of references of type T that have been attached or that are provided by Context objects.

Examples found in repository

examples/parse_config.rs (line 47)

fn main() {
    if let Err(report) = parse_config("config.json") {
        eprintln!("{report:?}");
        #[cfg(nightly)]
        for suggestion in report.request_ref::<Suggestion>() {
            eprintln!("Suggestion: {}", suggestion.0);
        }
    }
}

pub fn request_value<T: Send + Sync + 'static>(&self) -> RequestValue<'_, T>

Available on nightly only.

Creates an iterator of values of type T that have been attached or that are provided by Context objects.

pub fn contains<T: Send + Sync + 'static>(&self) -> bool

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

T could either be an attachment or a 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: Send + Sync + 'static>(&self) -> Option<&T>

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

T can either be an attachment or a 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: Send + Sync + 'static>(&mut self) -> Option<&mut T>

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

T can either be an attachment or a Context.

impl<C> Report<[C]>

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

Return 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 Frames, 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);

Examples found in repository

examples/demo.rs (line 41)

fn parse_experiment(description: &str) -> Result<Vec<(u64, u64)>, Report<ParseExperimentError>> {
    let values = description
        .split(' ')
        .map(|value| {
            value
                .parse::<u64>()
                .attach_with(|| format!("{value:?} could not be parsed as experiment"))
        })
        .map(|value| value.map(|ok| (ok, 2 * ok)))
        .fold(Ok(vec![]), |accum, value| match (accum, value) {
            (Ok(mut accum), Ok(value)) => {
                accum.push(value);

                Ok(accum)
            }
            (Ok(_), Err(err)) => Err(err.expand()),
            (Err(accum), Ok(_)) => Err(accum),
            (Err(mut accum), Err(err)) => {
                accum.push(err);

                Err(accum)
            }
        })
        .change_context(ParseExperimentError)?;

    Ok(values)
}

#[derive(Debug)]
struct ExperimentError;

impl fmt::Display for ExperimentError {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.write_str("experiment error: could not run experiment")
    }
}

impl Error for ExperimentError {}

#[expect(
    clippy::manual_try_fold,
    reason = "false-positive, try_fold is fail-fast, our implementation is fail-slow"
)]
fn start_experiments(
    experiment_ids: &[usize],
    experiment_descriptions: &[&str],
) -> Result<Vec<u64>, Report<[ExperimentError]>> {
    let experiments = experiment_ids
        .iter()
        .map(|exp_id| {
            let description = experiment_descriptions.get(*exp_id).ok_or_else(|| {
                Report::new(ExperimentError)
                    .attach(format!("experiment {exp_id} has no valid description"))
            })?;

            let experiments = parse_experiment(description)
                .attach(format!("experiment {exp_id} could not be parsed"))
                .change_context(ExperimentError)?;

            let experiments = experiments
                .into_iter()
                .map(|(lhs, rhs)| move || lhs * rhs)
                .collect::<Vec<_>>();

            Ok(experiments)
        })
        .fold(
            Ok(vec![]),
            |accum, value: Result<_, Report<ExperimentError>>| match (accum, value) {
                (Ok(mut accum), Ok(value)) => {
                    accum.extend(value);

                    Ok(accum)
                }
                (Ok(_), Err(err)) => Err(err.expand()),
                (Err(accum), Ok(_)) => Err(accum),
                (Err(mut accum), Err(err)) => {
                    accum.push(err);

                    Err(accum)
                }
            },
        )
        .attach("unable to set up experiments")?;

    Ok(experiments.iter().map(|experiment| experiment()).collect())
}

pub fn append(&mut self, report: Self)

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)

Set 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:

invalid input parameter
├╴at libs/error-stack/src/fmt/charset.rs:24:42
├╴backtrace (1)
╰╴📝 oh no, try again

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

backtrace no. 1
  [redacted]

invalid input parameter
|-at libs/error-stack/src/fmt/charset.rs:24:42
|-backtrace (1)
|-suggestion: oh no, try again

========================================

backtrace no. 1
  [redacted]

Examples found in repository

examples/detect.rs (line 61)

fn main() {
    // error-stack only uses ANSI codes for colors
    let supports_color = supports_color::on_cached(supports_color::Stream::Stdout)
        .is_some_and(|level| level.has_basic);

    let color_mode = if supports_color {
        ColorMode::Color
    } else {
        ColorMode::None
    };

    let supports_unicode = supports_unicode::on(supports_unicode::Stream::Stdout);

    let charset = if supports_unicode {
        Charset::Utf8
    } else {
        Charset::Ascii
    };

    Report::set_color_mode(color_mode);
    Report::set_charset(charset);

    if let Err(err) = parse_config("config.json") {
        // if you would use `eprintln!` instead, you should check support on `Stream::Stderr`
        // instead.
        println!("{err:?}");
    }
}

impl Report<()>

pub fn set_color_mode(mode: ColorMode)

Set 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:

invalid input parameter
├╴at libs/error-stack/src/fmt/color.rs:27:42
├╴backtrace (1)
╰╴suggestion: oh no, try again

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

backtrace no. 1
  [redacted]

invalid input parameter
├╴at libs/error-stack/src/fmt/color.rs:27:42
├╴backtrace (1)
╰╴suggestion: oh no, try again

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

backtrace no. 1
  [redacted]

invalid input parameter
├╴at libs/error-stack/src/fmt/color.rs:27:42
├╴backtrace (1)
╰╴suggestion: oh no, try again

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

backtrace no. 1
  [redacted]

Examples found in repository

examples/detect.rs (line 60)

fn main() {
    // error-stack only uses ANSI codes for colors
    let supports_color = supports_color::on_cached(supports_color::Stream::Stdout)
        .is_some_and(|level| level.has_basic);

    let color_mode = if supports_color {
        ColorMode::Color
    } else {
        ColorMode::None
    };

    let supports_unicode = supports_unicode::on(supports_unicode::Stream::Stdout);

    let charset = if supports_unicode {
        Charset::Utf8
    } else {
        Charset::Ascii
    };

    Report::set_color_mode(color_mode);
    Report::set_charset(charset);

    if let Err(err) = parse_config("config.json") {
        // if you would use `eprintln!` instead, you should check support on `Stream::Stderr`
        // instead.
        println!("{err:?}");
    }
}

impl Report<()>

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

Available on crate features std or hooks only.

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:

invalid input parameter
├╴at libs/error-stack/src/hook/mod.rs:22:42
├╴backtrace (1)
╰╴suggestion: oh no, try again

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

backtrace no. 1
  [redacted]

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:

invalid user input
├╴suggestion: try better next time!
├╴error code: 420
├╴at libs/error-stack/src/hook/mod.rs:51:47
╰╴backtrace (1)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

backtrace no. 1
  [redacted]

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:

invalid input parameter
╰╴backtrace (1)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

backtrace no. 1
  [redacted]

Trait Implementations

impl<C: ?Sized> Debug for Report<C>

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

Formats the value using the given formatter.

impl<C: ?Sized> Display for Report<C>

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

Formats the value using the given formatter.

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

fn extend<T: IntoIterator<Item = Self>>(&mut self, iter: T)

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: IntoIterator<Item = Report<C>>>(&mut self, iter: T)

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: Context,

fn from(context: C) -> Self

Converts to this type from the input type.

impl<C: 'static> From<Report<C>> for Box<dyn Error>

fn from(report: Report<C>) -> Self

Converts to this type from the input type.

impl<C: 'static> From<Report<C>> for Box<dyn Error + Send>

fn from(report: Report<C>) -> Self

Converts to this type from the input type.

impl<C: 'static> From<Report<C>> for Box<dyn Error + Send + Sync>

fn from(report: Report<C>) -> Self

Converts to this type from the input type.

impl<C: 'static> From<Report<C>> for Box<dyn Error + Sync>

fn from(report: Report<C>) -> Self

Converts to this type from the input type.

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

fn from(report: Report<C>) -> Self

Converts to this type from the input type.

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

fn from_iter<T: IntoIterator<Item = Report<[C]>>>(iter: T) -> Self

Creates a value from an iterator.

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

fn from_iter<T: IntoIterator<Item = Report<C>>>(iter: T) -> Self

Creates a value from an iterator.

impl<C: ?Sized> IntoReport for Report<C>

type Context = C

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

fn into_report(self) -> Report<Self::Context>

Converts this value into a Report.

impl<C: Context> Serialize for Report<[C]>

Available on crate feature serde only.

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<C: Context> Serialize for Report<C>

Available on crate feature serde only.

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

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.