thiserror 1.0.69

derive(Error)

This library provides a convenient derive macro for the standard library'sstd::error::Error trait.

[dependencies]thiserror="1.0"

Compiler support: requires rustc 1.61+

Example

usethiserror::Error;#[derive(Error, Debug)]pubenumDataStoreError{#[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,}

Details

• Thiserror deliberately does not appear in your public API. You get the samething as if you had written an implementation ofstd::error::Error by hand,and switching from handwritten impls to thiserror or vice versa is not abreaking change.

• Errors may be enums, structs with named fields, tuple structs, or unitstructs.

• ADisplay impl is generated for your error if you provide#[error("...")]messages on the struct or each variant of your enum, as shown above in theexample.

  The messages support a shorthand for interpolating fields from the error.

  • #[error("{var}")] ⟶ write!("{}", self.var)
  • #[error("{0}")] ⟶ write!("{}", self.0)
  • #[error("{var:?}")] ⟶ write!("{:?}", self.var)
  • #[error("{0:?}")] ⟶ write!("{:?}", self.0)

  These shorthands can be used together with any additional format args, whichmay be arbitrary expressions. For example:

  #[derive(Error, Debug)]pubenumError{#[error("invalid rdo_lookahead_frames {0} (expected < {})", i32::MAX)]    InvalidLookahead(u32),}

  If one of the additional expression arguments needs to refer to a field of thestruct or enum, then refer to named fields as.var and tuple fields as.0.

  #[derive(Error, Debug)]pubenumError{#[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},}

• AFrom impl is generated for each variant that contains a#[from]attribute.

  The variant using#[from] must not contain any other fields beyond thesource error (and possibly a backtrace — see below). Usually#[from]fields are unnamed, but#[from] is allowed on a named field too.

  #[derive(Error, Debug)]pubenumMyError{    Io(#[from]io::Error),    Glob(#[from]globset::Error),}

• The Error trait'ssource() method is implemented to return whichever fieldhas a#[source] attribute or is namedsource, if any. This is foridentifying the underlying lower level error that caused your error.

  The#[from] attribute always implies that the same field is#[source], soyou don't ever need to specify both attributes.

  Any error type that implementsstd::error::Error or dereferences todyn std::error::Error will work as a source.

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

• The Error trait'sprovide() method is implemented to provide whichever fieldhas a type namedBacktrace, if any, as astd::backtrace::Backtrace. UsingBacktrace in errors requires a nightly compiler with Rust version 1.73 ornewer.

  usestd::backtrace::Backtrace;#[derive(Error, Debug)]pubstructMyError{msg: String,backtrace: Backtrace,// automatically detected}

• If a field is both a source (namedsource, or has#[source] or#[from]attribute)and is marked#[backtrace], then the Error trait'sprovide()method is forwarded to the source'sprovide so that both layers of the errorshare the same backtrace. The#[backtrace] attribute requires a nightlycompiler with Rust version 1.73 or newer.

  #[derive(Error, Debug)]pubenumMyError{    Io{#[backtrace]        source:io::Error,},}

• For variants that use#[from] and also contain aBacktrace field, abacktrace is captured from within theFrom impl.

  #[derive(Error, Debug)]pubenumMyError{    Io{#[from]        source:io::Error,        backtrace: Backtrace,},}

• Errors may useerror(transparent) to forward the source and Display methodsstraight through to an underlying error without adding an additional message.This would be appropriate for enums that need an "anything else" variant.

  #[derive(Error, Debug)]pubenumMyError{...#[error(transparent)]    Other(#[from]anyhow::Error),// source and Display delegate to anyhow::Error}

  Another use case is hiding implementation details of an error representationbehind an opaque error type, so that the representation is able to evolvewithout breaking the crate's public API.

  // PublicError is public, but opaque and easy to keep compatible.#[derive(Error, Debug)]#[error(transparent)]pubstructPublicError(#[from] ErrorRepr);implPublicError{// Accessors for anything we do want to expose publicly.}// Private and free to change across minor version of the crate.#[derive(Error, Debug)]enumErrorRepr{...}

• See also theanyhow library for a convenient single error type to use inapplication code.

Comparison to anyhow

Use thiserror if you care about designing your own dedicated error type(s) sothat the caller receives exactly the information that you choose in the event offailure. This most often applies to library-like code. UseAnyhow if you don'tcare what error type your functions return, you just want it to be easy. This iscommon in application-like code.

License