[announcement post]: https://hash.dev/blog/announcing-error-stack
[crates.io]: https://crates.io/crates/error-stack
[libs.rs]: https://lib.rs/crates/error-stack
[rust-version]: https://www.rust-lang.org
[documentation]: https://docs.rs/error-stack
[license]: https://github.com/hashintel/hash/blob/main/libs/error-stack/LICENSE.md

[![crates.io](https://img.shields.io/crates/v/error-stack)][crates.io]
[![libs.rs](https://img.shields.io/badge/libs.rs-error--stack-orange)][libs.rs]
[![rust-version](https://img.shields.io/static/v1?label=Rust&message=1.83.0/nightly-2026-08-03&color=blue)][rust-version]
[![documentation](https://img.shields.io/docsrs/error-stack)][documentation]
[![license](https://img.shields.io/crates/l/error-stack)][license]

[Open issues](https://github.com/hashintel/hash/issues?q=is%3Aissue+is%3Aopen+label%3AA-error-stack) / [Discussions](https://github.com/hashintel/hash/discussions?discussions_q=label%3AA-error-stack)

# 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 core::{error::Error, fmt};

use error_stack::{Report, ResultExt};

#[derive(Debug)]
struct ParseExperimentError;

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

impl Error for ParseExperimentError {}

fn parse_experiment(description: &str) -> Result<(u64, u64), Report<ParseExperimentError>> {
    let value = description
        .parse::<u64>()
        .attach_with(|| 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.write_str("experiment error: could not run experiment")
    }
}

impl Error for ExperimentError {}

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 experiment = parse_experiment(description)
                .attach(format!("experiment {exp_id} could not be parsed"))
                .change_context(ExperimentError)?;

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

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

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

    Ok(())
}
```

This will most likely result in an error and print

<pre>
Error: <b>experiment error: could not run experiment</b>
&#x251C;&#x2574;at <i>examples/demo.rs:50:18</i>
&#x251C;&#x2574;unable to set up experiments
&#x2502;
&#x251C;&#x2500;&#x25B6; <b>invalid experiment description</b>
&#x2502;   &#x251C;&#x2574;at <i>examples/demo.rs:20:10</i>
&#x2502;   &#x2570;&#x2574;experiment 2 could not be parsed
&#x2502;
&#x2570;&#x2500;&#x25B6; <b>invalid digit found in string</b>
    &#x251C;&#x2574;at <i>examples/demo.rs:19:10</i>
    &#x251C;&#x2574;backtrace with 31 frames (1)
    &#x2570;&#x2574;&quot;3o&quot; could not be parsed as experiment

&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;

backtrace no. 1
   0: std::backtrace_rs::backtrace::libunwind::trace
             at /rustc/f3623871cfa0763c95ebd6ceafaa6dc2e44ca68f/library/std/src/../../backtrace/src/backtrace/libunwind.rs:93:5
   1: std::backtrace_rs::backtrace::trace_unsynchronized
             at /rustc/f3623871cfa0763c95ebd6ceafaa6dc2e44ca68f/library/std/src/../../backtrace/src/backtrace/mod.rs:66:5
   2: std::backtrace::Backtrace::create
             at /rustc/f3623871cfa0763c95ebd6ceafaa6dc2e44ca68f/library/std/src/backtrace.rs:331:13
   3: core::ops::function::FnOnce::call_once
             at /rustc/f3623871cfa0763c95ebd6ceafaa6dc2e44ca68f/library/core/src/ops/function.rs:250:5
   4: core::bool::&lt;impl bool&gt;::then
             at /rustc/f3623871cfa0763c95ebd6ceafaa6dc2e44ca68f/library/core/src/bool.rs:60:24
   5: error_stack::report::Report&lt;C&gt;::from_frame
             at ./src/report.rs:286:25
   6: error_stack::report::Report&lt;C&gt;::new
             at ./src/report.rs:272:9
   7: error_stack::context::&lt;impl core::convert::From&lt;C&lt; for error_stack::report::Report&lt;C&gt;&gt;::from
             at ./src/context.rs:83:9
   8: &lt;core::result::Result&lt;T,C&lt; as error_stack::result::ResultExt&lt;::attach_with
             at ./src/result.rs:158:31
   9: demo::parse_experiment
             at demo.rs:17:17
  10: demo::start_experiments::{{closure}}
             at demo.rs:48:30
   (<b>For this example:</b> additional frames have been removed)
</pre>

## Usage

Please see the [documentation].

For more examples of `error-stack` in use, please check out the [examples](https://github.com/hashintel/hash/tree/main/libs/error-stack/examples) folder.

## Contributors

`error-stack` was created and is maintained by [HASH](https://hash.dev/). As an open-source project, we gratefully accept external contributions and have published a [contributing guide](https://github.com/hashintel/hash/blob/main/.github/CONTRIBUTING.md) that outlines the process. If you have questions, please create a [GitHub discussion](https://github.com/orgs/hashintel/discussions).

## License

`error-stack` is available under either of the [Apache License, Version 2.0] or [MIT license] at your option. Please see the [LICENSE] file for more information.
