thiserror

https://docs.rs/thiserror/latest/
Admin
thiserror is a Rust library that provides a convenient derive macro for implementing the standard...
Tokens:6,477
Snippets:79
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Custom Error Message Formatting with thiserror

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

This example demonstrates advanced formatting for error messages using thiserror. It shows how to interpolate fields and use arbitrary expressions within the #[error(...)] attribute.

```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),
}
```

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

### Forward Backtrace to Source

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

When a field is both a source and marked `#[backtrace]`, the `provide()` method forwards to the source's `provide` for shared backtrace information. Requires a nightly compiler.

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

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

### Placeholder for Non-Std Environments

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

Provides a placeholder implementation of AsDisplay and related traits for environments where the 'std' feature is not enabled, preventing compilation issues.

```rust
#[cfg(not(feature = "std"))]
mod placeholder {
    use super::{AsDisplay, Sealed};
    use core::fmt::{self, Display};

    #[allow(dead_code)]
    pub struct Placeholder;

    impl<'a> AsDisplay<'a> for Placeholder {
        type Target = Self;

        #[inline]
        fn as_display(&'a self) -> Self::Target {
            Placeholder
        }
    }

    impl Display for Placeholder {
        fn fmt(&self, _formatter: &mut fmt::Formatter) -> fmt::Result {
            unreachable!()
        }
    }

    impl Sealed for Placeholder {}
}
```

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

### Forward backtrace from a source error

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

When a source error is also marked with `#[backtrace]`, the `provide` method forwards the backtrace to the source. Requires a nightly compiler (Rust 1.73+).

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

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

### Transparent Error Forwarding

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

Use `#[error(transparent)]` to delegate `Display` and `source()` methods to an underlying error without adding a custom message. Useful for 'catch-all' variants.

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

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

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

### Implement Error Source Method

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

Use `#[source]` or a field named `source` to implement the `Error::source()` method, indicating the underlying error.

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

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

### Capture Backtrace with #[from]

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

For variants using `#[from]`, a `Backtrace` field will capture the backtrace within the `From` implementation. Requires a nightly compiler.

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

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

### AsDisplay Trait and Implementations

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

Defines the AsDisplay trait for converting types to a Display-compatible format. Includes implementations for generic references, Path, and PathBuf, with conditional compilation for std.

```rust
use core::fmt::Display;
#[cfg(feature = "std")]
use std::path::{self, Path, PathBuf};

#[doc(hidden)]
pub trait AsDisplay<'a>: Sealed {
    // TODO: convert to generic associated type.
    // https://github.com/dtolnay/thiserror/pull/253
    type Target: Display;

    fn as_display(&'a self) -> Self::Target;
}

impl<'a, T> AsDisplay<'a> for &T
where
    T: Display + ?Sized + 'a,
{
    type Target = &'a T;

    fn as_display(&'a self) -> Self::Target {
        *self
    }
}

#[cfg(feature = "std")]
impl<'a> AsDisplay<'a> for Path {
    type Target = path::Display<'a>;

    #[inline]
    fn as_display(&'a self) -> Self::Target {
        self.display()
    }
}

#[cfg(feature = "std")]
impl<'a> AsDisplay<'a> for PathBuf {
    type Target = path::Display<'a>;

    #[inline]
    fn as_display(&'a self) -> Self::Target {
        self.display()
    }
}

#[doc(hidden)]
pub trait Sealed {}
impl<T: Display + ?Sized> Sealed for &T {}
#[cfg(feature = "std")]
impl Sealed for Path {}
#[cfg(feature = "std")]
impl Sealed for PathBuf {}
```

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

### Automatic Backtrace Capture

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

Include a `Backtrace` field to automatically capture and provide backtrace information when the error is formatted. Requires a nightly compiler.

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

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

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

### Implement Pointer for Var Wrapper

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

This snippet shows the implementation of the `Pointer` trait for the `Var` struct. It delegates the formatting to the underlying type `T` which must also implement `Pointer`.

```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)
    }
}

```

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

### Automatic From Implementation for Error Variants

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

The `#[from]` attribute automatically generates an implementation of `From<SourceError>` for your error type, allowing for easy error conversion.

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

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

### Capture backtrace within a `#[from]` variant

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

For variants using `#[from]`, a backtrace is captured from within the `From` implementation. Requires a nightly compiler (Rust 1.73+).

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

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

### ThiserrorProvide Trait and Implementation

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

This snippet shows the definition of the `ThiserrorProvide` trait and its blanket implementation for any type that implements the `core::error::Error` trait. It allows for providing error information through a `Request` object.

```APIDOC
## ThiserrorProvide Trait and Implementation

### Description
This section details the `ThiserrorProvide` trait, which is part of the `thiserror` crate. It defines a method `thiserror_provide` that allows an error type to provide information about itself via a `Request` object. A blanket implementation is provided for all types that implement `core::error::Error`.

### Trait Definition
```rust
use core::error::{Error, Request};

#[doc(hidden)]
pub trait ThiserrorProvide: Sealed {
    fn thiserror_provide<'a>(&'a self, request: &mut Request<'a>);
}
```

### Implementation
```rust
impl<T> ThiserrorProvide for T
where
    T: Error + ?Sized,
{
    #[inline]
    fn thiserror_provide<'a>(&'a self, request: &mut Request<'a>) {
        self.provide(request);
    }
}
```

### Sealed Trait
```rust
#[doc(hidden)]
pub trait Sealed {}
impl<T: Error + ?Sized> Sealed for T {}
```
```

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

### Implement ThiserrorProvide Trait

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

This snippet implements the `ThiserrorProvide` trait for any type that implements the standard `Error` trait. It forwards the `provide` call to the underlying `Error` implementation.

```rust
use core::error::{Error, Request};

#[doc(hidden)]
pub trait ThiserrorProvide: Sealed {
    fn thiserror_provide<'a>(&'a self, request: &mut Request<'a>);
}

implement<T>
where
    T: Error + ?Sized,
{
    #[inline]
    fn thiserror_provide<'a>(&'a self, request: &mut Request<'a>) {
        self.provide(request);
    }
}

#[doc(hidden)]
pub trait Sealed {}
implement<T: Error + ?Sized> Sealed for T {}
```

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

### thiserror Derive Macro Attributes

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

Illustrates the attributes available for the `#[derive(Error)]` macro in the `thiserror` crate. Use these attributes to configure error display, backtraces, and source chaining.

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

```

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

### Define Custom Error with Display Message

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

Use `#[error("...")]` to generate a `Display` implementation for your error type. Supports field interpolation using `{var}` or `{0}` syntax.

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

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

### Define a custom error with a source

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

Define a custom error type that includes another error as its source. This is useful for wrapping underlying errors.

```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!()
#     }
# }
```

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

### Error Formatting with Field References in thiserror

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

Illustrates how to reference struct fields directly within error message formatting strings in thiserror. Supports both named and tuple struct fields.

```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,
    },
}
```

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

### Implementing From Trait with #[from] in thiserror

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

This snippet shows how to automatically implement the From trait for different error types using the #[from] attribute in thiserror. This simplifies error conversion and chaining.

```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 {
    #[from] Io(io::Error),
    #[from] Glob(globset::Error),
}

impl Display for MyError {
    fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
        unimplemented!()
    }
}
```

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

### Implement AsDynError for Error Types

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

This implementation allows various error types, including boxed dynamic errors with different trait bounds, to be converted into a reference to a dynamic Error trait object.

```rust
use core::error::Error;
use core::panic::UnwindSafe;

#[doc(hidden)]
pub trait AsDynError<'a>: Sealed {
    fn as_dyn_error(&self) -> &(dyn Error + 'a);
}

impl<'a, T: Error + 'a> AsDynError<'a> for T {
    #[inline]
    fn as_dyn_error(&self) -> &(dyn Error + 'a) {
        self
    }
}

impl<'a> AsDynError<'a> for dyn Error + 'a {
    #[inline]
    fn as_dyn_error(&self) -> &(dyn Error + 'a) {
        self
    }
}

impl<'a> AsDynError<'a> for dyn Error + Send + 'a {
    #[inline]
    fn as_dyn_error(&self) -> &(dyn Error + 'a) {
        self
    }
}

impl<'a> AsDynError<'a> for dyn Error + Send + Sync + 'a {
    #[inline]
    fn as_dyn_error(&self) -> &(dyn Error + 'a) {
        self
    }
}

impl<'a> AsDynError<'a> for dyn Error + Send + Sync + UnwindSafe + 'a {
    #[inline]
    fn as_dyn_error(&self) -> &(dyn Error + 'a) {
        self
    }
}
```

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

### AsDynError Trait and Implementations

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

This section details the `AsDynError` trait, which is used to convert various error types into a dynamic `dyn Error` type. It includes implementations for different error trait bounds.

```APIDOC
## Trait: AsDynError<'a>

### Description
Trait to convert various error types into a dynamic `dyn Error + 'a`.

### Methods
- `as_dyn_error(&self) -> &(dyn Error + 'a)`: Converts the implementing type into a dynamic error trait object.

### Implementations

#### `impl<'a, T: Error + 'a> AsDynError<'a> for T`
Converts a concrete `T: Error` into `dyn Error + 'a`.

#### `impl<'a> AsDynError<'a> for dyn Error + 'a`
Identity conversion for existing `dyn Error + 'a`.

#### `impl<'a> AsDynError<'a> for dyn Error + Send + 'a`
Converts `dyn Error + Send + 'a` into `dyn Error + 'a`.

#### `impl<'a> AsDynError<'a> for dyn Error + Send + Sync + 'a`
Converts `dyn Error + Send + Sync + 'a` into `dyn Error + 'a`.

#### `impl<'a> AsDynError<'a> for dyn Error + Send + Sync + UnwindSafe + 'a`
Converts `dyn Error + Send + Sync + UnwindSafe + 'a` into `dyn Error + 'a`.

## Trait: Sealed

### Description
A private trait used to prevent downstream implementations of `AsDynError`.

### Implementations

#### `impl<T: Error> Sealed for T`
Implementation for concrete error types.

#### `impl Sealed for dyn Error + '_`
Implementation for dynamic error types.

#### `impl Sealed for dyn Error + Send + '_`
Implementation for dynamic error types with `Send` bound.

#### `impl Sealed for dyn Error + Send + Sync + '_`
Implementation for dynamic error types with `Send + Sync` bounds.

#### `impl Sealed for dyn Error + Send + Sync + UnwindSafe + '_`
Implementation for dynamic error types with `Send + Sync + UnwindSafe` bounds.
```

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

### Interpolate Fields in Error Messages

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

Error messages can interpolate fields using `.var` for named fields or `.0` for tuple fields. Additional format arguments can be arbitrary expressions.

```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 },
}
```

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

### Internal Re-exports for thiserror Crate

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

This snippet shows internal re-exports for the thiserror crate. It includes re-exports for AsDynError, AsDisplay, ThiserrorProvide, Var, and the standard Error trait. Conditional re-exports for Backtrace are included when the 'std' feature is enabled and 'thiserror_no_backtrace_type' is not.

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

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

### Opaque Public Error Type

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

Define a public struct with `#[error(transparent)]` that wraps a private error representation. This allows the internal error details 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 {
    ...
}
```

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

### Define Custom Error Enum with thiserror

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

Use this macro to define custom error types with specific error messages and automatic trait implementations. Requires importing `thiserror::Error` and `std::error::Error`.

```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,
}
```

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

### Implement Sealed Trait for Error Types

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

The Sealed trait is used internally to restrict trait implementations. These implementations cover concrete error types and various forms of dynamic error trait objects.

```rust
#[doc(hidden)]
pub trait Sealed {}
impl<T: Error> Sealed for T {}
impl Sealed for dyn Error + '_ {}
impl Sealed for dyn Error + Send + '_ {}
impl Sealed for dyn Error + Send + Sync + '_ {}
impl Sealed for dyn Error + Send + Sync + UnwindSafe + '_ {}
```

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

### Deriving Error Enum with thiserror

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

Use this derive macro to define custom error types. It automatically implements std::error::Error and Display traits. Supports various error variants including disconnected states, redactions, and invalid headers.

```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