Open issues / Discussions

error-stack

error-stack is a context-aware error-handling library that supports arbitrary attached user data.

Read our [announcement post] for the story behind its origins.

The library enables building a Report around an error as it propagates:

```rust use std::fmt;

use error_stack::{Context, IntoReport, Report, Result, ResultExt};

[derive(Debug)]

struct ParseExperimentError;

impl fmt::Display for ParseExperimentError { fn fmt(&self, fmt: &mut fmt::Formatter<'>) -> fmt::Result { fmt.writestr("invalid experiment description") } }

impl Context for ParseExperimentError {}

fn parseexperiment(description: &str) -> Result<(u64, u64), ParseExperimentError> { let value = description .parse() .intoreport() .attachprintablelazy(|| format!("{description:?} could not be parsed as experiment")) .change_context(ParseExperimentError)?;

Ok((value, 2 * value))

}

[derive(Debug)]

struct ExperimentError;

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

impl Context for ExperimentError {}

fn startexperiments( experimentids: &[usize], experimentdescriptions: &[&str], ) -> Result, ExperimentError> { let experiments = experimentids .iter() .map(|expid| { let description = experimentdescriptions.get(*expid).okorelse(|| { Report::new(ExperimentError) .attachprintable(format!("experiment {exp_id} has no valid description")) })?;

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

        Ok(move || experiment.0 * experiment.1)
    })
    .collect::<Result<Vec<_>, ExperimentError>>()
    .attach_printable("unable to set up experiments")?;

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

}

fn main() -> Result<(), ExperimentError> { let experimentids = &[0, 2]; let experimentdescriptions = &["10", "20", "3o"]; startexperiments(experimentids, experiment_descriptions)?;

Ok(())

} ```

This will most likely result in an error and print

Error: experiment error: could not run experiment
├╴at examples/demo.rs:51:18
├╴unable to set up experiments
│
├─▶ invalid experiment description
│   ├╴at examples/demo.rs:21:10
│   ╰╴experiment 2 could not be parsed
│
╰─▶ invalid digit found in string
    ├╴at examples/demo.rs:19:10
    ├╴backtrace with 31 frames (1)
    ╰╴"3o" could not be parsed as experiment

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

backtrace no. 1
   0: std::backtrace_rs::backtrace::libunwind::trace
             at /rustc/e972bc8083d5228536dfd42913c8778b6bb04c8e/library/std/src/../../backtrace/src/backtrace/libunwind.rs:93:5
   1: std::backtrace_rs::backtrace::trace_unsynchronized
             at /rustc/e972bc8083d5228536dfd42913c8778b6bb04c8e/library/std/src/../../backtrace/src/backtrace/mod.rs:66:5
   2: std::backtrace::Backtrace::create
             at /rustc/e972bc8083d5228536dfd42913c8778b6bb04c8e/library/std/src/backtrace.rs:332:13
   3: core::ops::function::FnOnce::call_once
             at /rustc/e972bc8083d5228536dfd42913c8778b6bb04c8e/library/core/src/ops/function.rs:250:5
   4: core::bool::<impl bool>::then
             at /rustc/e972bc8083d5228536dfd42913c8778b6bb04c8e/library/core/src/bool.rs:71:24
   5: error_stack::report::Report<C>::from_frame
             at ./src/report.rs:288:25
   6: error_stack::report::Report<C>::new
             at ./src/report.rs:274:9
   7: error_stack::context::<impl core::convert::From<C> for error_stack::report::Report<C>>::from
             at ./src/context.rs:83:9
   8: <core::result::Result<T,E> as error_stack::result::IntoReport>::into_report
             at ./src/result.rs:203:31
   (For this example: additional frames have been removed)

Usage

Please see the [documentation].

For more examples of error-stack in use, please check out the examples folder.

Contributors

error-stack was created and is maintained by HASH. As an open-source project, we gratefully accept external contributions and have published a contributing guide that outlines the process. If you have questions, please reach out to us on our Discord server.

License

error-stack is available under a number of different open-source licenses. Please see the [LICENSE] file to review your options.