Trait ErrorTrait 

pub trait ErrorTrait: Debug + Display {
    // Provided methods
    fn source(&self) -> Option<&(dyn Error + 'static)> { ... }
    fn description(&self) -> &str { ... }
    fn cause(&self) -> Option<&dyn Error> { ... }
    fn provide<'a>(&'a self, request: &mut Request<'a>) { ... }
}

Error is a trait representing the basic expectations for error values, i.e., values of type E in Result<T, E>.

Errors must describe themselves through the Display and Debug traits. Error messages are typically concise lowercase sentences without trailing punctuation:

let err = "NaN".parse::<u32>().unwrap_err();
assert_eq!(err.to_string(), "invalid digit found in string");

Error source

Errors may provide cause information. Error::source() is generally used when errors cross “abstraction boundaries”. If one module must report an error that is caused by an error from a lower-level module, it can allow accessing that error via Error::source(). This makes it possible for the high-level module to provide its own errors while also revealing some of the implementation for debugging.

In error types that wrap an underlying error, the underlying error should be either returned by the outer error’s Error::source(), or rendered by the outer error’s Display implementation, but not both.

Example

Implementing the Error trait only requires that Debug and Display are implemented too.

use std::error::Error;
use std::fmt;
use std::path::PathBuf;

#[derive(Debug)]
struct ReadConfigError {
    path: PathBuf
}

impl fmt::Display for ReadConfigError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let path = self.path.display();
        write!(f, "unable to read configuration at {path}")
    }
}

impl Error for ReadConfigError {}

Provided Methods

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

Examples

use std::error::Error;
use std::fmt;

#[derive(Debug)]
struct SuperError {
    source: SuperErrorSideKick,
}

impl fmt::Display for SuperError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "SuperError is here!")
    }
}

impl Error for SuperError {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        Some(&self.source)
    }
}

#[derive(Debug)]
struct SuperErrorSideKick;

impl fmt::Display for SuperErrorSideKick {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "SuperErrorSideKick is here!")
    }
}

impl Error for SuperErrorSideKick {}

fn get_super_error() -> Result<(), SuperError> {
    Err(SuperError { source: SuperErrorSideKick })
}

fn main() {
    match get_super_error() {
        Err(e) => {
            println!("Error: {e}");
            println!("Caused by: {}", e.source().unwrap());
        }
        _ => println!("No error"),
    }
}

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

if let Err(e) = "xc".parse::<u32>() {
    // Print `e` itself, no need for description().
    eprintln!("Error: {e}");
}

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

Used in conjunction with Request::provide_value and Request::provide_ref to extract references to member variables from dyn Error trait objects.

Example

#![feature(error_generic_member_access)]
use core::fmt;
use core::error::{request_ref, Request};

#[derive(Debug)]
enum MyLittleTeaPot {
    Empty,
}

#[derive(Debug)]
struct MyBacktrace {
    // ...
}

impl MyBacktrace {
    fn new() -> MyBacktrace {
        // ...
    }
}

#[derive(Debug)]
struct Error {
    backtrace: MyBacktrace,
}

impl fmt::Display for Error {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "Example Error")
    }
}

impl std::error::Error for Error {
    fn provide<'a>(&'a self, request: &mut Request<'a>) {
        request
            .provide_ref::<MyBacktrace>(&self.backtrace);
    }
}

fn main() {
    let backtrace = MyBacktrace::new();
    let error = Error { backtrace };
    let dyn_error = &error as &dyn std::error::Error;
    let backtrace_ref = request_ref::<MyBacktrace>(dyn_error).unwrap();

    assert!(core::ptr::eq(&error.backtrace, backtrace_ref));
    assert!(request_ref::<MyLittleTeaPot>(dyn_error).is_none());
}

Delegating Impls

Warning: We recommend implementors avoid delegating implementations of provide to source error implementations.

This method should expose context from the current piece of the source chain only, not from sources that are exposed in the chain of sources. Delegating provide implementations cause the same context to be provided by multiple errors in the chain of sources which can cause unintended duplication of information in error reports or require heuristics to deduplicate.

In other words, the following implementation pattern for provide is discouraged and should not be used for Error types exposed in public APIs to third parties.

struct MyError {
    source: Error,
}

impl std::error::Error for MyError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        Some(&self.source)
    }

    fn provide<'a>(&'a self, request: &mut Request<'a>) {
        self.source.provide(request) // <--- Discouraged
    }
}

Implementations

impl dyn Error

pub fn is<T>(&self) -> bool

where T: Error + 'static,

Returns true if the inner type is the same as T.

pub fn downcast_ref<T>(&self) -> Option<&T>

where T: Error + 'static,

Returns some reference to the inner value if it is of type T, or None if it isn’t.

pub fn downcast_mut<T>(&mut self) -> Option<&mut T>

where T: Error + 'static,

Returns some mutable reference to the inner value if it is of type T, or None if it isn’t.

impl dyn Error + Send

pub fn is<T>(&self) -> bool

where T: Error + 'static,

Forwards to the method defined on the type dyn Error.

pub fn downcast_ref<T>(&self) -> Option<&T>

where T: Error + 'static,

Forwards to the method defined on the type dyn Error.

pub fn downcast_mut<T>(&mut self) -> Option<&mut T>

where T: Error + 'static,

Forwards to the method defined on the type dyn Error.

impl dyn Error + Send + Sync

pub fn is<T>(&self) -> bool

where T: Error + 'static,

Forwards to the method defined on the type dyn Error.

pub fn downcast_ref<T>(&self) -> Option<&T>

where T: Error + 'static,

Forwards to the method defined on the type dyn Error.

pub fn downcast_mut<T>(&mut self) -> Option<&mut T>

where T: Error + 'static,

Forwards to the method defined on the type dyn Error.

impl dyn Error

pub fn sources(&self) -> Source<'_>

🔬This is a nightly-only experimental API. (error_iter)

Returns an iterator starting with the current error and continuing with recursively calling Error::source.

If you want to omit the current error and only use its sources, use skip(1).

Examples

#![feature(error_iter)]
use std::error::Error;
use std::fmt;

#[derive(Debug)]
struct A;

#[derive(Debug)]
struct B(Option<Box<dyn Error + 'static>>);

impl fmt::Display for A {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "A")
    }
}

impl fmt::Display for B {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "B")
    }
}

impl Error for A {}

impl Error for B {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        self.0.as_ref().map(|e| e.as_ref())
    }
}

let b = B(Some(Box::new(A)));

// let err : Box<Error> = b.into(); // or
let err = &b as &dyn Error;

let mut iter = err.sources();

assert_eq!("B".to_string(), iter.next().unwrap().to_string());
assert_eq!("A".to_string(), iter.next().unwrap().to_string());
assert!(iter.next().is_none());
assert!(iter.next().is_none());

Trait Implementations

impl<'a> From<&str> for Box<dyn Error + 'a>

Available on non-no_global_oom_handling only.

fn from(err: &str) -> Box<dyn Error + 'a>

Converts a str into a box of dyn Error.

Examples

use std::error::Error;

let a_str_error = "a str error";
let a_boxed_error = Box::<dyn Error>::from(a_str_error);
assert!(size_of::<Box<dyn Error>>() == size_of_val(&a_boxed_error))

impl<'a> From<&str> for Box<dyn Error + Send + Sync + 'a>

Available on non-no_global_oom_handling only.

fn from(err: &str) -> Box<dyn Error + Send + Sync + 'a>

Converts a str into a box of dyn Error + Send + Sync.

Examples

use std::error::Error;

let a_str_error = "a str error";
let a_boxed_error = Box::<dyn Error + Send + Sync>::from(a_str_error);
assert!(
    size_of::<Box<dyn Error + Send + Sync>>() == size_of_val(&a_boxed_error))

impl<'a, 'b> From<Cow<'b, str>> for Box<dyn Error + 'a>

Available on non-no_global_oom_handling only.

fn from(err: Cow<'b, str>) -> Box<dyn Error + 'a>

Converts a Cow into a box of dyn Error.

Examples

use std::error::Error;
use std::borrow::Cow;

let a_cow_str_error = Cow::from("a str error");
let a_boxed_error = Box::<dyn Error>::from(a_cow_str_error);
assert!(size_of::<Box<dyn Error>>() == size_of_val(&a_boxed_error))

impl<'a, 'b> From<Cow<'b, str>> for Box<dyn Error + Send + Sync + 'a>

Available on non-no_global_oom_handling only.

fn from(err: Cow<'b, str>) -> Box<dyn Error + Send + Sync + 'a>

Converts a Cow into a box of dyn Error + Send + Sync.

Examples

use std::error::Error;
use std::borrow::Cow;

let a_cow_str_error = Cow::from("a str error");
let a_boxed_error = Box::<dyn Error + Send + Sync>::from(a_cow_str_error);
assert!(
    size_of::<Box<dyn Error + Send + Sync>>() == size_of_val(&a_boxed_error))

impl<'a, E> From<E> for Box<dyn Error + 'a>

where E: Error + 'a,

Available on non-no_global_oom_handling only.

fn from(err: E) -> Box<dyn Error + 'a>

Converts a type of Error into a box of dyn Error.

Examples

use std::error::Error;
use std::fmt;

#[derive(Debug)]
struct AnError;

impl fmt::Display for AnError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "An error")
    }
}

impl Error for AnError {}

let an_error = AnError;
assert!(0 == size_of_val(&an_error));
let a_boxed_error = Box::<dyn Error>::from(an_error);
assert!(size_of::<Box<dyn Error>>() == size_of_val(&a_boxed_error))

impl<'a, E> From<E> for Box<dyn Error + Send + Sync + 'a>

where E: Error + Send + Sync + 'a,

Available on non-no_global_oom_handling only.

fn from(err: E) -> Box<dyn Error + Send + Sync + 'a>

Converts a type of Error + Send + Sync into a box of dyn Error + Send + Sync.

Examples

use std::error::Error;
use std::fmt;

#[derive(Debug)]
struct AnError;

impl fmt::Display for AnError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "An error")
    }
}

impl Error for AnError {}

unsafe impl Send for AnError {}

unsafe impl Sync for AnError {}

let an_error = AnError;
assert!(0 == size_of_val(&an_error));
let a_boxed_error = Box::<dyn Error + Send + Sync>::from(an_error);
assert!(
    size_of::<Box<dyn Error + Send + Sync>>() == size_of_val(&a_boxed_error))

impl<'a> From<String> for Box<dyn Error + 'a>

Available on non-no_global_oom_handling only.

fn from(str_err: String) -> Box<dyn Error + 'a>

Converts a String into a box of dyn Error.

Examples

use std::error::Error;

let a_string_error = "a string error".to_string();
let a_boxed_error = Box::<dyn Error>::from(a_string_error);
assert!(size_of::<Box<dyn Error>>() == size_of_val(&a_boxed_error))

impl<'a> From<String> for Box<dyn Error + Send + Sync + 'a>

Available on non-no_global_oom_handling only.

fn from(err: String) -> Box<dyn Error + Send + Sync + 'a>

Converts a String into a box of dyn Error + Send + Sync.

Examples

use std::error::Error;

let a_string_error = "a string error".to_string();
let a_boxed_error = Box::<dyn Error + Send + Sync>::from(a_string_error);
assert!(
    size_of::<Box<dyn Error + Send + Sync>>() == size_of_val(&a_boxed_error))

impl Value for dyn Error

Available on crate feature std only.

fn record(&self, key: &Field, visitor: &mut dyn Visit)

Visits this value with the given Visitor.

impl Value for dyn Error + Send

Available on crate feature std only.

fn record(&self, key: &Field, visitor: &mut dyn Visit)

Visits this value with the given Visitor.

impl Value for dyn Error + Send + Sync

Available on crate feature std only.

fn record(&self, key: &Field, visitor: &mut dyn Visit)

Visits this value with the given Visitor.

impl Value for dyn Error + Sync

Available on crate feature std only.

fn record(&self, key: &Field, visitor: &mut dyn Visit)

Visits this value with the given Visitor.

Implementors

impl !Error for &str

impl Error for Infallible

impl Error for FromBytesWithNulError

impl Error for core::slice::GetDisjointMutError

impl Error for VarError

impl Error for std::fs::TryLockError

impl Error for std::sync::mpsc::RecvTimeoutError

impl Error for std::sync::mpsc::TryRecvError

impl Error for ParseAlphabetError

Available on crate features std only.

impl Error for DecodeError

Available on crate features std only.

impl Error for DecodeSliceError

Available on crate features std only.

impl Error for EncodeSliceError

Available on crate features std only.

impl Error for MatchesError

impl Error for httparse::Error

Available on crate feature std only.

impl Error for indexmap::GetDisjointMutError

Available on crate feature std only.

impl Error for Errno

impl Error for prometheus::errors::Error

impl Error for ProtobufError

impl Error for BernoulliError

Available on crate feature std only.

impl Error for WeightedError

Available on crate feature std only.

impl Error for regex_automata::dfa::automaton::StartError

Available on crate feature std only.

impl Error for regex_automata::hybrid::error::StartError

Available on crate feature std only.

impl Error for regex_syntax::error::Error

Available on crate feature std only.

impl Error for regex::error::Error

Available on crate feature std only.

impl Error for slab::GetDisjointMutError

Available on crate feature std only.

impl Error for StrSimError

impl Error for ParseError

Available on crate feature std only.

impl Error for AnyDelimiterCodecError

impl Error for LinesCodecError

impl Error for TryAcquireError

impl Error for tokio::sync::broadcast::error::RecvError

impl Error for tokio::sync::broadcast::error::TryRecvError

impl Error for tokio::sync::mpsc::error::TryRecvError

impl Error for tokio::sync::oneshot::error::TryRecvError

impl Error for !

impl Error for UnorderedKeyError

impl Error for alloc::collections::TryReserveError

impl Error for FromVecWithNulError

impl Error for IntoStringError

impl Error for NulError

impl Error for alloc::string::FromUtf8Error

impl Error for FromUtf16Error

impl Error for LayoutError

impl Error for AllocError

impl Error for TryFromSliceError

impl Error for BorrowError

impl Error for BorrowMutError

impl Error for CharTryFromError

impl Error for ParseCharError

impl Error for DecodeUtf16Error

impl Error for TryFromCharError

impl Error for FromBytesUntilNulError

impl Error for core::fmt::Error

impl Error for AddrParseError

impl Error for ParseFloatError

impl Error for ParseIntError

impl Error for TryFromIntError

impl Error for ParseBoolError

impl Error for core::str::error::Utf8Error

impl Error for TryFromFloatSecsError

impl Error for JoinPathsError

impl Error for WriterPanicked

impl Error for std::io::error::Error

impl Error for NormalizeError

impl Error for StripPrefixError

impl Error for ExitStatusError

impl Error for std::sync::mpsc::RecvError

impl Error for AccessError

impl Error for SystemTimeError

impl Error for aho_corasick::util::error::BuildError

Available on crate feature std only.

impl Error for aho_corasick::util::error::MatchError

Available on crate feature std only.

impl Error for aho_corasick::util::primitives::PatternIDError

Available on crate feature std only.

impl Error for aho_corasick::util::primitives::StateIDError

Available on crate feature std only.

impl Error for bstr::ext_vec::FromUtf8Error

Available on crate feature std only.

impl Error for bstr::utf8::Utf8Error

Available on crate feature std only.

impl Error for TryGetError

Available on crate feature std only.

impl Error for daemonize::error::Error

impl Error for CompressError

impl Error for DecompressError

impl Error for futures_channel::mpsc::SendError

impl Error for futures_channel::mpsc::TryRecvError

impl Error for Canceled

Available on crate feature std only.

impl Error for EnterError

impl Error for SpawnError

Available on crate feature std only.

impl Error for Aborted

Available on crate feature std only.

impl Error for getrandom::error::Error

impl Error for h2::error::Error

impl Error for http::error::Error

impl Error for MaxSizeReached

impl Error for InvalidHeaderName

impl Error for InvalidHeaderValue

impl Error for ToStrError

impl Error for InvalidMethod

impl Error for InvalidStatusCode

impl Error for InvalidUri

impl Error for InvalidUriParts

impl Error for httpdate::Error

impl Error for indexmap::TryReserveError

Available on crate feature std only.

impl Error for ClearEnvError

impl Error for pingora_timeout::Elapsed

impl Error for ReadError

impl Error for rand_core::error::Error

Available on crate feature std only.

impl Error for regex_automata::dfa::onepass::BuildError

Available on crate feature std only.

impl Error for regex_automata::hybrid::error::BuildError

Available on crate feature std only.

impl Error for CacheError

Available on crate feature std only.

impl Error for regex_automata::meta::error::BuildError

Available on crate feature std only.

impl Error for regex_automata::nfa::thompson::error::BuildError

Available on crate feature std only.

impl Error for GroupInfoError

Available on crate feature std only.

impl Error for UnicodeWordBoundaryError

Available on crate feature std only.

impl Error for regex_automata::util::primitives::PatternIDError

Available on crate feature std only.

impl Error for SmallIndexError

Available on crate feature std only.

impl Error for regex_automata::util::primitives::StateIDError

Available on crate feature std only.

impl Error for regex_automata::util::search::MatchError

Available on crate feature std only.

impl Error for PatternSetInsertError

Available on crate feature std only.

impl Error for DeserializeError

Available on crate feature std only.

impl Error for SerializeError

Available on crate feature std only.

impl Error for regex_syntax::ast::Error

Available on crate feature std only.

impl Error for regex_syntax::hir::Error

Available on crate feature std only.

impl Error for CaseFoldError

Available on crate feature std only.

impl Error for UnicodeWordError

Available on crate feature std only.

impl Error for serde_core::de::value::Error

Available on crate feature std only.

impl Error for serde_yaml::error::Error

impl Error for tokio_stream::stream_ext::timeout::Elapsed

impl Error for LengthDelimitedCodecError

impl Error for tokio::net::tcp::split_owned::ReuniteError

impl Error for tokio::net::unix::split_owned::ReuniteError

impl Error for TryCurrentError

impl Error for JoinError

impl Error for AcquireError

impl Error for tokio::sync::mutex::TryLockError

impl Error for tokio::sync::oneshot::error::RecvError

impl Error for tokio::sync::watch::error::RecvError

impl Error for tokio::time::error::Elapsed

impl Error for tokio::time::error::Error

impl Error for SetGlobalDefaultError

Available on crate feature std only.

impl Error for ParseLevelError

Available on crate feature std only.

impl Error for ParseLevelFilterError

Available on crate feature std only.

impl Error for ConnectProxyError

impl Error for pingora_core::Error

impl<'a, K, V> Error for alloc::collections::btree::map::entry::OccupiedError<'a, K, V>

where K: Debug + Ord, V: Debug,

impl<'a, K, V, A> Error for std::collections::hash::map::OccupiedError<'a, K, V, A>

where K: Debug, V: Debug, A: Allocator,

impl<'a, T> Error for &'a T

where T: Error + ?Sized,

impl<A, S, V> Error for ConvertError<A, S, V>

where A: Display + Debug, S: Display + Debug, V: Display + Debug,

Available on zerocopy_core_error_1_81_0 or crate feature std only.

impl<E> Error for Box<E>

where E: Error,

impl<F> Error for clap_builder::error::Error<F>

where F: ErrorFormatter,

impl<Src, Dst> Error for AlignmentError<Src, Dst>

where Src: Deref, Dst: KnownLayout + ?Sized,

Available on zerocopy_core_error_1_81_0 or crate feature std only.

impl<Src, Dst> Error for SizeError<Src, Dst>

where Src: Deref, Dst: KnownLayout + ?Sized,

Available on zerocopy_core_error_1_81_0 or crate feature std only.

impl<Src, Dst> Error for ValidityError<Src, Dst>

where Dst: KnownLayout + TryFromBytes + ?Sized,

Available on zerocopy_core_error_1_81_0 or crate feature std only.

impl<T> Error for std::sync::mpmc::error::SendTimeoutError<T>

impl<T> Error for std::sync::mpsc::TrySendError<T>

impl<T> Error for std::sync::oneshot::RecvTimeoutError<T>

impl<T> Error for std::sync::oneshot::TryRecvError<T>

impl<T> Error for std::sync::poison::TryLockError<T>

impl<T> Error for tokio::sync::mpsc::error::SendTimeoutError<T>

Available on crate feature time only.

impl<T> Error for tokio::sync::mpsc::error::TrySendError<T>

impl<T> Error for SetError<T>

where T: Debug,

impl<T> Error for ThinBox<T>

where T: Error + ?Sized,

impl<T> Error for Arc<T>

where T: Error + ?Sized,

impl<T> Error for std::sync::mpsc::SendError<T>

impl<T> Error for PoisonError<T>

impl<T> Error for futures_channel::mpsc::TrySendError<T>

where T: Any,

impl<T> Error for futures_util::io::split::ReuniteError<T>

where T: Any,

Available on crate feature std only.

impl<T> Error for PollSendError<T>

where T: Debug,

impl<T> Error for AsyncFdTryNewError<T>

impl<T> Error for tokio::sync::broadcast::error::SendError<T>

where T: Debug,

impl<T> Error for tokio::sync::mpsc::error::SendError<T>

impl<T> Error for SetOnceError<T>

where T: Debug,

impl<T> Error for tokio::sync::watch::error::SendError<T>

impl<T, E> Error for TryChunksError<T, E>

where E: Debug + Display,

Available on crate feature std only.

impl<T, E> Error for TryReadyChunksError<T, E>

where E: Debug + Display,

Available on crate feature std only.

impl<T, Item> Error for futures_util::stream::stream::split::ReuniteError<T, Item>

where T: Any,

Available on crate feature std only.

impl<W> Error for IntoInnerError<W>

where W: Send + Debug,