7 releases

0.0.6 Feb 23, 2022
0.0.5 Feb 23, 2022
0.0.0 Jan 21, 2022

#185 in Rust patterns

Download history 7675/week @ 2022-12-04 7032/week @ 2022-12-11 6902/week @ 2022-12-18 3553/week @ 2022-12-25 6101/week @ 2023-01-01 7068/week @ 2023-01-08 8501/week @ 2023-01-15 7159/week @ 2023-01-22 6430/week @ 2023-01-29 6440/week @ 2023-02-05 7296/week @ 2023-02-12 6951/week @ 2023-02-19 7695/week @ 2023-02-26 7837/week @ 2023-03-05 7880/week @ 2023-03-12 9001/week @ 2023-03-19

32,847 downloads per month


171 lines

crates.io CI commits-since rust 1.51.0+ badge


A generative approach to creating fatal and non-fatal errors.

The generated source utilizes thiserror::Error derived attributes heavily, and any unknown annotations will be passed to that.


For large scale mono-repos, with subsystems it eventually becomes very tedious to match against nested error variants defined with thiserror. Using anyhow or eyre - while it being an application - also comes with an unmanagable amount of pain for medium-large scale code bases.

fatality is a solution to this, by extending thiserror::Error with annotations to declare certain variants as fatal, or forward the fatality extraction to an inner error type.

Read on!


#[fatality] currently provides a trait Fatality with a single fn is_fatal(&self) -> bool by default.

Annotations with forward require the inner error type to also implement trait Fatality.

Annotating with #[fatality(splitable)], allows to split the type into two sub-types, a Jfyi* and a Fatal* one via fn split(self) -> Result<Self::Jfyi, Self::Fatal>. If splitable is annotated.

The derive macro implements them, and can defer calls, based on thiserror annotations, specifically #[source] and #[transparent] on enum variants and their members.

/// Fatality only works with `enum` for now.
/// It will automatically add `#[derive(Debug, thiserror::Error)]`
/// annotations.
enum OhMy {
    #[error("An apple a day")]

    /// Forwards the `is_fatal` to the `InnerError`, which has to implement `trait Fatality` as well.
    #[error("Dropped dead")]
    ReallyReallyBad(#[source] InnerError),

    /// Also works on `#[error(transparent)]

    /// Will always return `is_fatal` as `true`,
    /// irrespective of `#[error(transparent)]` or
    /// `#[source]` annotations.
    #[error("So dead")]
    SoDead(#[source] InnerError),
enum Yikes {
    #[error("An apple a day")]

    #[error("So dead")]

fn foo() -> Result<[u8;32], Yikes> {

fn i_call_foo() -> Result<(), FatalYikes> {
    // availble via a convenience trait `Nested` that is implemented
    // for any `Result` whose error type implements `Split`.
    let x: Result<[u8;32], Jfyi> = foo().into_nested()?;

fn i_call_foo_too() -> Result<(), FatalYikes> {
    if let Err(jfyi_and_fatal_ones) = foo() {
        // bail if bad, otherwise just log it
        log::warn!("Jfyi: {:?}", jfyi_and_fatal_ones.split()?);


  • Optionally reduce the marco overhead, replace #[fatal($args)]#[error(.. with #[fatal($args;..)] and generate the correct #[error] annotations for thiserror.
  • Add an optional arg to finality: splitable determines if a this is the root error that shall be handled, and hence should be splitable into two enums Fatal and Jfyi errors, with trait Split and fn split() -> Result<Jfyi, Fatal> {..}.
  • Allow annotations for structs as well, to be all fatal or informational.


~97K SLoC