Thiserror

https://docs.rs/thiserror/2.0.18
Admin
Thiserror is a Rust derive macro library that provides a convenient and ergonomic way to implement...
Tokens:6,263
Snippets:66
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Error with #[backtrace] Attribute

Source: https://docs.rs/thiserror/2.0.18/src/thiserror/lib.rs.html

Mark a source field with `#[backtrace]` to have the `provide()` method forward to the source's `provide` method. This requires a nightly compiler (Rust 1.73+).

```rust
# const IGNORE: &str = stringify! {
#[derive(Error, Debug)]
pub enum MyError {
    Io {
        #[backtrace]
        source: io::Error,
    },
}
# };
```

--------------------------------

### Implement AsDisplay trait for display formatting

Source: https://docs.rs/thiserror/2.0.18/src/thiserror/display.rs.html

Provides a trait for converting types to a displayable target, with specific implementations for references, paths, and path buffers.

```rust
1use core::fmt::Display;
2#[cfg(feature = "std")]
3use std::path::{self, Path, PathBuf};
4
5#[doc(hidden)]
6pub trait AsDisplay<'a>: Sealed {
7    // TODO: convert to generic associated type.
8    // https://github.com/dtolnay/thiserror/pull/253
9    type Target: Display;
10
11    fn as_display(&'a self) -> Self::Target;
12}
13
14impl<'a, T> AsDisplay<'a> for &T
15where
16    T: Display + ?Sized + 'a,
17{
18    type Target = &'a T;
19
20    fn as_display(&'a self) -> Self::Target {
21        *self
22    }
23}
24
25#[cfg(feature = "std")]
26impl<'a> AsDisplay<'a> for Path {
27    type Target = path::Display<'a>;
28
29    #[inline]
30    fn as_display(&'a self) -> Self::Target {
31        self.display()
32    }
33}
34
35#[cfg(feature = "std")]
36impl<'a> AsDisplay<'a> for PathBuf {
37    type Target = path::Display<'a>;
38
39    #[inline]
40    fn as_display(&'a self) -> Self::Target {
41        self.display()
42    }
43}
44
45#[doc(hidden)]
46pub trait Sealed {}
47impl<T: Display + ?Sized> Sealed for &T {}
48#[cfg(feature = "std")]
49impl Sealed for Path {}
50#[cfg(feature = "std")]
51impl Sealed for PathBuf {}
52
53// Add a synthetic second impl of AsDisplay to prevent the "single applicable
54// impl" rule from making too weird inference decision based on the single impl
55// for &T, which could lead to code that compiles with thiserror's std feature
56// off but breaks under feature unification when std is turned on by an
57// unrelated crate.
58#[cfg(not(feature = "std"))]
59mod placeholder {
60    use super::{AsDisplay, Sealed};
61    use core::fmt::{self, Display};
62
63    #[allow(dead_code)]
64    pub struct Placeholder;
65
66    impl<'a> AsDisplay<'a> for Placeholder {
67        type Target = Self;
68
69        #[inline]
70        fn as_display(&'a self) -> Self::Target {
71            Placeholder
72        }
73    }
74
75    impl Display for Placeholder {
76        fn fmt(&self, _formatter: &mut fmt::Formatter) -> fmt::Result {
77            unreachable!()
78        }
79    }
80
81    impl Sealed for Placeholder {}
82}
```

--------------------------------

### Integrating Backtraces into Errors

Source: https://docs.rs/thiserror/2.0.18/thiserror/index.html

Include a `Backtrace` field to automatically populate the `Error::provide()` method. Requires a nightly compiler (Rust 1.73+).

```rust
use std::backtrace::Backtrace;

#[derive(Error, Debug)]
pub struct MyError {
    msg: String,
    backtrace: Backtrace,  // automatically detected
}
```

--------------------------------

### Error with #[from] and Backtrace

Source: https://docs.rs/thiserror/2.0.18/src/thiserror/lib.rs.html

For variants using `#[from]` and containing a `Backtrace` field, a backtrace is captured from within the `From` implementation. This requires a nightly compiler.

```rust
# const IGNORE: &str = stringify! {
#[derive(Error, Debug)]
pub enum MyError {
    Io {
        #[from]
        source: io::Error,
        backtrace: Backtrace,
    },
}
# };
```

--------------------------------

### Implement Pointer for Var Wrapper

Source: https://docs.rs/thiserror/2.0.18/src/thiserror/var.rs.html

This snippet shows how to implement the `Pointer` trait for the `Var` struct. It delegates the formatting to the inner type's `Pointer` implementation.

```rust
use core::fmt::{self, Pointer};

pub struct Var<'a, T: ?Sized>(pub &'a T);

impl<'a, T: Pointer + ?Sized> Pointer for Var<'a, T> {
    fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
        Pointer::fmt(self.0, formatter)
    }
}
```

--------------------------------

### Transparent Error Forwarding

Source: https://docs.rs/thiserror/2.0.18/thiserror

Use `#[error(transparent)]` to forward `source` and `Display` methods to an underlying error without adding a new message. Useful for 'anything else' variants or hiding implementation details.

```rust
#[derive(Error, Debug)]
pub enum MyError {
    ...

    #[error(transparent)]
    Other(#[from] anyhow::Error),  // source and Display delegate to anyhow::Error
}
```

--------------------------------

### Transparent Error Forwarding

Source: https://docs.rs/thiserror/2.0.18/thiserror/index.html

Use `#[error(transparent)]` to forward `source()` and `Display` methods to an underlying error without adding a new message. Useful for "anything else" variants or opaque error types.

```rust
#[derive(Error, Debug)]
pub enum MyError {
    ...

    #[error(transparent)]
    Other(#[from] anyhow::Error),  // source and Display delegate to anyhow::Error
}
```

```rust
// PublicError is public, but opaque and easy to keep compatible.
#[derive(Error, Debug)]
#[error(transparent)]
pub struct PublicError(#[from] ErrorRepr);

impl PublicError {
    // Accessors for anything we do want to expose publicly.
}

// Private and free to change across minor version of the crate.
#[derive(Error, Debug)]
enum ErrorRepr {
    ...
}
```

--------------------------------

### Capturing Backtrace in From Impl

Source: https://docs.rs/thiserror/2.0.18/thiserror/index.html

For variants using `#[from]`, a backtrace is captured automatically if a `Backtrace` field is present. Requires a nightly compiler (Rust 1.73+).

```rust
#[derive(Error, Debug)]
pub enum MyError {
    Io {
        #[from]
        source: io::Error,
        backtrace: Backtrace,
    },
}
```

--------------------------------

### Automatic From Implementation for Error Variants

Source: https://docs.rs/thiserror/2.0.18/thiserror/index.html

Use `#[from]` to automatically implement `From<SourceError>` for enum variants. The variant must only contain the source error, optionally with a backtrace.

```rust
#[derive(Error, Debug)]
pub enum MyError {
    Io(#[from] io::Error),
    Glob(#[from] globset::Error),
}
```

--------------------------------

### Opaque Public Error Wrapper

Source: https://docs.rs/thiserror/2.0.18/thiserror

Demonstrates creating an opaque public error type by wrapping a private `ErrorRepr` using `#[error(transparent)]`. This allows the internal representation to change without breaking the public API.

```rust
// PublicError is public, but opaque and easy to keep compatible.
#[derive(Error, Debug)]
#[error(transparent)]
pub struct PublicError(#[from] ErrorRepr);

impl PublicError {
    // Accessors for anything we do want to expose publicly.
}

// Private and free to change across minor version of the crate.
#[derive(Error, Debug)]
enum ErrorRepr {
    ...
}
```

--------------------------------

### Implement From Trait for Error Variants

Source: https://docs.rs/thiserror/2.0.18/src/thiserror/lib.rs.html

Use the #[from] attribute to automatically generate From implementations for error variants.

```rust
# use core::fmt::{self, Display};
# use std::io;
# use thiserror::Error;
#
# mod globset {
#     #[derive(thiserror::Error, Debug)]
#     #[error("...")]
#     pub struct Error;
# }
#
#[derive(Error, Debug)]
pub enum MyError {
    Io(#[from] io::Error),
    Glob(#[from] globset::Error),
}
#
# impl Display for MyError {
#     fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
#         unimplemented!()
#     }
# }
```

--------------------------------

### Implementing Error Source Chaining

Source: https://docs.rs/thiserror/2.0.18/thiserror/index.html

Implement the `Error::source()` method by marking a field with `#[source]` or naming it `source`. The `#[from]` attribute also implies `#[source]`.

```rust
#[derive(Error, Debug)]
pub struct MyError {
    msg: String,
    #[source]  // optional if field name is `source`
    source: anyhow::Error,
}
```

--------------------------------

### Trait: ThiserrorProvide

Source: https://docs.rs/thiserror/2.0.18/src/thiserror/provide.rs.html

An internal trait used to facilitate error provision within the thiserror crate.

```APIDOC
## Trait: ThiserrorProvide

### Description
A hidden trait used to provide error context. It is implemented for all types that satisfy the `core::error::Error` trait.

### Methods
- **thiserror_provide<'a>(&'a self, request: &mut Request<'a>)**: Provides the error context to the given request object.
```

--------------------------------

### Reference Fields in Error Messages

Source: https://docs.rs/thiserror/2.0.18/index.html

Refer to named fields using .var and tuple fields using .0 within the error message format string.

```rust
#[derive(Error, Debug)]
pub enum Error {
    #[error("first letter must be lowercase but was {:?}", first_char(.0))]
    WrongCase(String),
    #[error("invalid index {idx}, expected at least {} and at most {}", .limits.lo, .limits.hi)]
    OutOfBounds { idx: usize, limits: Limits },
}
```

--------------------------------

### Interpolate Fields with Additional Arguments

Source: https://docs.rs/thiserror/2.0.18/src/thiserror/lib.rs.html

Use additional format arguments in the error message, referencing struct fields with .var or .0 syntax.

```rust
# use core::i32;
# use thiserror::Error;
#
#[derive(Error, Debug)]
pub enum Error {
    #[error("invalid rdo_lookahead_frames {0} (expected < {max})", max = i32::MAX)]
    InvalidLookahead(u32),
}
```

--------------------------------

### Implement ThiserrorProvide trait

Source: https://docs.rs/thiserror/2.0.18/src/thiserror/provide.rs.html

Internal trait used to facilitate error provision, implemented for all types that satisfy the core::error::Error trait.

```rust
1use core::error::{Error, Request};
2
3#[doc(hidden)]
4pub trait ThiserrorProvide: Sealed {
5    fn thiserror_provide<'a>(&'a self, request: &mut Request<'a>);
6}
7
8impl<T> ThiserrorProvide for T
9where
10    T: Error + ?Sized,
11{
12    #[inline]
13    fn thiserror_provide<'a>(&'a self, request: &mut Request<'a>) {
14        self.provide(request);
15    }
16}
17
18#[doc(hidden)]
19pub trait Sealed {}
20impl<T: Error + ?Sized> Sealed for T {}
```

--------------------------------

### Sharing Backtraces Between Error Layers

Source: https://docs.rs/thiserror/2.0.18/thiserror/index.html

Use `#[backtrace]` on a source field to share the same backtrace across error layers. Requires a nightly compiler (Rust 1.73+).

```rust
#[derive(Error, Debug)]
pub enum MyError {
    Io {
        #[backtrace]
        source: io::Error,
    },
}
```

--------------------------------

### Error Derive Macro

Source: https://docs.rs/thiserror/2.0.18/thiserror/derive.Error.html

The #[derive(Error)] macro allows for the creation of custom error types with convenient formatting and error chaining.

```APIDOC
## Derive Macro Error

### Description
This section describes the `#[derive(Error)]` macro provided by the `thiserror` crate for defining custom error types in Rust.

### Method
Derive Macro

### Endpoint
N/A (This is a Rust derive macro)

### Parameters
#### Attributes available to this derive:
- **`#[backtrace]`** (attribute) - Enables backtrace support for the error.
- **`#[error]`** (attribute) - Defines the display format for the error.
- **`#[from]`** (attribute) - Allows automatic conversion from other error types.
- **`#[source]`** (attribute) - Specifies the underlying error source.

### Request Example
```rust
use thiserror::Error;

#[derive(Error, Debug)]
pub enum MyError {
    #[error("Failed to read file: {0}")]
    Io(#[from] std::io::Error),
    #[error("Invalid data: {0}")]
    DataError(String),
    #[error("Network error: {0}")]
    NetworkError(#[from] reqwest::Error),
}
```

### Response
#### Success Response (N/A for derive macros)

#### Response Example
(N/A for derive macros)
```

--------------------------------

### Internal re-exports for thiserror

Source: https://docs.rs/thiserror/2.0.18/src/thiserror/private.rs.html

These items are marked with #[doc(hidden)] and are intended for internal use within the crate.

```rust
1#[doc(hidden)]
2pub use crate::aserror::AsDynError;
3#[doc(hidden)]
4pub use crate::display::AsDisplay;
5#[cfg(error_generic_member_access)]
6#[doc(hidden)]
7pub use crate::provide::ThiserrorProvide;
8#[doc(hidden)]
9pub use crate::var::Var;
10#[doc(hidden)]
11pub use core::error::Error;
12#[cfg(all(feature = "std", not(thiserror_no_backtrace_type)))]
13#[doc(hidden)]
14pub use std::backtrace::Backtrace;
```

--------------------------------

### Implement Error with thiserror

Source: https://docs.rs/thiserror/2.0.18/thiserror/index.html

Use the Error derive macro to define custom error types with associated error messages and source conversion.

```rust
use thiserror::Error;

#[derive(Error, Debug)]
pub enum DataStoreError {
    #[error("data store disconnected")]
    Disconnect(#[from] io::Error),
    #[error("the data for key `{0}` is not available")]
    Redaction(String),
    #[error("invalid header (expected {expected:?}, found {found:?})")]
    InvalidHeader {
        expected: String,
        found: String,
    },
    #[error("unknown data store error")]
    Unknown,
}
```

--------------------------------

### Error with Backtrace Field

Source: https://docs.rs/thiserror/2.0.18/src/thiserror/lib.rs.html

Include a `Backtrace` field in your error type. This requires a nightly compiler (Rust 1.73+) and automatically provides backtrace information when the error is formatted.

```rust
# const IGNORE: &str = stringify! {
use std::backtrace::Backtrace;

#[derive(Error, Debug)]
pub struct MyError {
    msg: String,
    backtrace: Backtrace,  // automatically detected
}
# };
```

--------------------------------

### Reference Fields in Error Messages

Source: https://docs.rs/thiserror/2.0.18/src/thiserror/lib.rs.html

Access struct or enum fields within the error message using dot notation for complex expressions.

```rust
# use thiserror::Error;
#
# fn first_char(s: &String) -> char {
#     s.chars().next().unwrap()
# }
#
# #[derive(Debug)]
# struct Limits {
#     lo: usize,
#     hi: usize,
# }
#
#[derive(Error, Debug)]
pub enum Error {
    #[error("first letter must be lowercase but was {:?}", first_char(.0))]
    WrongCase(String),
    #[error("invalid index {idx}, expected at least {} and at most {}", .limits.lo, .limits.hi)]
    OutOfBounds { idx: usize, limits: Limits },
}
```

--------------------------------

### Custom Error Message with Field Interpolation

Source: https://docs.rs/thiserror/2.0.18/thiserror/index.html

Define custom error messages using `#[error(...)]` with field interpolation. Supports named fields (`.var`) and tuple fields (`.0`). Additional format arguments can be arbitrary expressions.

```rust
#[derive(Error, Debug)]
pub enum Error {
    #[error("invalid rdo_lookahead_frames {0} (expected < {max})", max = i32::MAX)]
    InvalidLookahead(u32),
}
```

```rust
#[derive(Error, Debug)]
pub enum Error {
    #[error("first letter must be lowercase but was {:?}", first_char(.0))]
    WrongCase(String),
    #[error("invalid index {idx}, expected at least {} and at most {}", .limits.lo, .limits.hi)]
    OutOfBounds { idx: usize, limits: Limits },
}
```

--------------------------------

### Opaque Public Error Type

Source: https://docs.rs/thiserror/2.0.18/src/thiserror/lib.rs.html

Use `#[error(transparent)]` on a public struct to wrap an internal error representation. This allows the internal representation to evolve without breaking the public API.

```rust
# use thiserror::Error;
# 
// PublicError is public, but opaque and easy to keep compatible.
#[derive(Error, Debug)]
#[error(transparent)]
pub struct PublicError(#[from] ErrorRepr);

impl PublicError {
    // Accessors for anything we do want to expose publicly.
}

// Private and free to change across minor version of the crate.
#[derive(Error, Debug)]
enum ErrorRepr {
    # /*
    ...
    # */
}

```

--------------------------------

### Define Custom Error with Source

Source: https://docs.rs/thiserror/2.0.18/src/thiserror/lib.rs.html

Define a custom error type that includes another error as its source. The `#[source]` attribute marks the field that holds the underlying error.

```rust
# use core::fmt::{self, Display};
# use thiserror::Error;
# 
# #[derive(Error, Debug)]
# pub struct MyError {
#     msg: String,
#     #[source]  // optional if field name is `source`
#     source: anyhow::Error,
# }
# 
# impl Display for MyError {
#     fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
#         unimplemented!()
#     }
# }
```

--------------------------------

### Define Error with Interpolated Arguments

Source: https://docs.rs/thiserror/2.0.18/index.html

Use arbitrary expressions in error messages by providing additional arguments to the #[error] attribute.

```rust
#[derive(Error, Debug)]
pub enum Error {
    #[error("invalid rdo_lookahead_frames {0} (expected < {max})", max = i32::MAX)]
    InvalidLookahead(u32),
}
```

--------------------------------

### Implement AsDynError trait

Source: https://docs.rs/thiserror/2.0.18/src/thiserror/aserror.rs.html

Defines the AsDynError trait and its implementations for various error trait object combinations to allow uniform access to the underlying Error trait.

```rust
1use core::error::Error;
2use core::panic::UnwindSafe;
3
4#[doc(hidden)]
5pub trait AsDynError<'a>: Sealed {
6    fn as_dyn_error(&self) -> &(dyn Error + 'a);
7}
8
9impl<'a, T: Error + 'a> AsDynError<'a> for T {
10    #[inline]
11    fn as_dyn_error(&self) -> &(dyn Error + 'a) {
12        self
13    }
14}
15
16impl<'a> AsDynError<'a> for dyn Error + 'a {
17    #[inline]
18    fn as_dyn_error(&self) -> &(dyn Error + 'a) {
19        self
20    }
21}
22
23impl<'a> AsDynError<'a> for dyn Error + Send + 'a {
24    #[inline]
25    fn as_dyn_error(&self) -> &(dyn Error + 'a) {
26        self
27    }
28}
29
30impl<'a> AsDynError<'a> for dyn Error + Send + Sync + 'a {
31    #[inline]
32    fn as_dyn_error(&self) -> &(dyn Error + 'a) {
33        self
34    }
35}
36
37impl<'a> AsDynError<'a> for dyn Error + Send + Sync + UnwindSafe + 'a {
38    #[inline]
39    fn as_dyn_error(&self) -> &(dyn Error + 'a) {
40        self
41    }
42}
43
44#[doc(hidden)]
45pub trait Sealed {}
46impl<T: Error> Sealed for T {}
47impl Sealed for dyn Error + '_ {}
48impl Sealed for dyn Error + Send + '_ {}
49impl Sealed for dyn Error + Send + Sync + '_ {}
50impl Sealed for dyn Error + Send + Sync + UnwindSafe + '_ {}
```

--------------------------------

### AsDynError Trait

Source: https://docs.rs/thiserror/2.0.18/src/thiserror/aserror.rs.html

The AsDynError trait provides a unified interface to convert error types into a reference to a dynamic Error trait object.

```APIDOC
## Trait: AsDynError

### Description
A hidden trait used to convert various error types into a reference to a dynamic Error trait object (&dyn Error).

### Methods
- **as_dyn_error(&self) -> &(dyn Error + 'a)**: Returns a reference to the underlying dynamic error.

### Implementations
- **T: Error + 'a**: Generic implementation for any type implementing the Error trait.
- **dyn Error + 'a**: Implementation for dynamic error trait objects.
- **dyn Error + Send + 'a**: Implementation for thread-safe dynamic error trait objects.
- **dyn Error + Send + Sync + 'a**: Implementation for thread-safe and sync-safe dynamic error trait objects.
- **dyn Error + Send + Sync + UnwindSafe + 'a**: Implementation for thread-safe, sync-safe, and unwind-safe dynamic error trait objects.
```

--------------------------------

### Derive Error Macro Attributes

Source: https://docs.rs/thiserror/2.0.18/thiserror/derive.Error.html

Available attributes for the Error derive macro in thiserror.

```rust
#[derive(Error)]
{
    // Attributes available to this derive:
    #[backtrace]
    #[error]
    #[from]
    #[source]
}
```

--------------------------------

### Define an Error Enum with thiserror

Source: https://docs.rs/thiserror/2.0.18/src/thiserror/lib.rs.html

Use the Error derive macro to define custom error types with Display messages and automatic error conversion.

```rust
# use std::io;
use thiserror::Error;

#[derive(Error, Debug)]
pub enum DataStoreError {
    #[error("data store disconnected")]
    Disconnect(#[from] io::Error),
    #[error("the data for key `{0}` is not available")]
    Redaction(String),
    #[error("invalid header (expected {expected:?}, found {found:?})")]
    InvalidHeader {
        expected: String,
        found: String,
    },
    #[error("unknown data store error")]
    Unknown,
}
```
Tokens:
Raw