# Trait std::error::Error

1.0.0 · source ·

    pub trait Error: 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>) { ... }
    }

Expand description

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

Run

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.

## Provided Methods§

1.30.0 · source

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

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

Run
source

#### 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}");
    }

Run
source

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

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

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

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

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)]
    #![feature(error_in_core)]
    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());
    }

Run

## Implementations§

source§

### impl dyn Error

1.3.0 · source

#### pub fn is<T>(&self) -> bool where T: Error + 'static,

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

1.3.0 · source

#### 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.

1.3.0 · source

#### 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.

source§

### impl dyn Error + Send

1.3.0 · source

#### pub fn is<T>(&self) -> bool where T: Error + 'static,

Forwards to the method defined on the type `dyn Error`.

1.3.0 · source

#### pub fn downcast_ref<T>(&self) -> Option<&T>where T: Error + 'static,

Forwards to the method defined on the type `dyn Error`.

1.3.0 · source

#### pub fn downcast_mut<T>(&mut self) -> Option<&mut T>where T: Error + 'static,

Forwards to the method defined on the type `dyn Error`.

source§

### impl dyn Error + Send + Sync

1.3.0 · source

#### pub fn is<T>(&self) -> bool where T: Error + 'static,

Forwards to the method defined on the type `dyn Error`.

1.3.0 · source

#### pub fn downcast_ref<T>(&self) -> Option<&T>where T: Error + 'static,

Forwards to the method defined on the type `dyn Error`.

1.3.0 · source

#### pub fn downcast_mut<T>(&mut self) -> Option<&mut T>where T: Error + 'static,

Forwards to the method defined on the type `dyn Error`.

source§

### impl dyn Error

source

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

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

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());

Run
source§

### impl dyn Error

1.3.0 · source

#### pub fn downcast<T>(self: Box<dyn Error>) -> Result<Box<T>, Box<dyn Error>>where T: Error + 'static,

Attempts to downcast the box to a concrete type.

source§

### impl dyn Error + Send

1.3.0 · source

#### pub fn downcast<T>( self: Box<dyn Error + Send> ) -> Result<Box<T>, Box<dyn Error + Send>>where T: Error + 'static,

Attempts to downcast the box to a concrete type.

source§

### impl dyn Error + Send + Sync

1.3.0 · source

#### pub fn downcast<T>( self: Box<dyn Error + Send + Sync> ) -> Result<Box<T>, Box<dyn Error + Send + Sync>>where T: Error + 'static,

Attempts to downcast the box to a concrete type.

## Trait Implementations§

1.6.0 · source§

### impl From<&str> for Box<dyn Error>

source§

#### fn from(err: &str) -> Box<dyn Error>

Converts a `str` into a box of dyn `Error`.

##### Examples

    use std::error::Error;
    use std::mem;

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

Run
source§

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

source§

#### 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;
    use std::mem;

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

Run
1.22.0 · source§

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

source§

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

Converts a `Cow` into a box of dyn `Error`.

##### Examples

    use std::error::Error;
    use std::mem;
    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!(mem::size_of::<Box<dyn Error>>() == mem::size_of_val(&a_boxed_error))

Run
1.22.0 · source§

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

source§

#### 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::mem;
    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!(
        mem::size_of::<Box<dyn Error + Send + Sync>>() == mem::size_of_val(&a_boxed_error))

Run
source§

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

source§

#### 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;
    use std::mem;

    #[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 == mem::size_of_val(&an_error));
    let a_boxed_error = Box::<dyn Error>::from(an_error);
    assert!(mem::size_of::<Box<dyn Error>>() == mem::size_of_val(&a_boxed_error))

Run
source§

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

source§

#### 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;
    use std::mem;

    #[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 == mem::size_of_val(&an_error));
    let a_boxed_error = Box::<dyn Error + Send + Sync>::from(an_error);
    assert!(
        mem::size_of::<Box<dyn Error + Send + Sync>>() == mem::size_of_val(&a_boxed_error))

Run
1.6.0 · source§

### impl From<String> for Box<dyn Error>

source§

#### fn from(str_err: String) -> Box<dyn Error>

Converts a `String` into a box of dyn `Error`.

##### Examples

    use std::error::Error;
    use std::mem;

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

Run
source§

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

source§

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

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

##### Examples

    use std::error::Error;
    use std::mem;

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

Run

## Implementors§

source§

### impl !Error for &str

1.8.0 · source§

### impl Error for Infallible

source§

### impl Error for VarError

1.15.0 · source§

### impl Error for RecvTimeoutError

source§

### impl Error for TryRecvError

source§

### impl Error for !

source§

### impl Error for AllocError

1.28.0 · source§

### impl Error for LayoutError

1.34.0 · source§

### impl Error for TryFromSliceError

1.13.0 · source§

### impl Error for BorrowError

1.13.0 · source§

### impl Error for BorrowMutError

1.34.0 · source§

### impl Error for CharTryFromError

1.9.0 · source§

### impl Error for DecodeUtf16Error

1.20.0 · source§

### impl Error for ParseCharError

1.59.0 · source§

### impl Error for TryFromCharError

1.57.0 · source§

### impl Error for TryReserveError

source§

### impl Error for JoinPathsError

1.69.0 · source§

### impl Error for FromBytesUntilNulError

1.17.0 · source§

### impl Error for FromBytesWithNulError

1.58.0 · source§

### impl Error for FromVecWithNulError

1.7.0 · source§

### impl Error for IntoStringError

source§

### impl Error for NulError

1.11.0 · source§

### impl Error for std::fmt::Error

source§

### impl Error for std::io::Error

1.56.0 · source§

### impl Error for WriterPanicked

1.4.0 · source§

### impl Error for AddrParseError

source§

### impl Error for ParseFloatError

source§

### impl Error for ParseIntError

1.34.0 · source§

### impl Error for TryFromIntError

1.63.0 · source§

### impl Error for InvalidHandleError

Available on Windows only.
1.63.0 · source§

### impl Error for NullHandleError

Available on Windows only.
1.7.0 · source§

### impl Error for StripPrefixError

source§

### impl Error for ExitStatusError

source§

### impl Error for ParseBoolError

source§

### impl Error for Utf8Error

source§

### impl Error for FromUtf8Error

source§

### impl Error for FromUtf16Error

source§

### impl Error for RecvError

1.26.0 · source§

### impl Error for AccessError

1.8.0 · source§

### impl Error for SystemTimeError

1.66.0 · source§

### impl Error for TryFromFloatSecsError

source§

### impl<'a, K, V> Error for std::collections::btree_map::OccupiedError<'a, K, V>where K: Debug + Ord, V: Debug,

source§

### impl<'a, K: Debug, V: Debug> Error for std::collections::hash_map::OccupiedError<'a, K, V>

1.51.0 · source§

### impl<'a, T> Error for &'a T where T: Error + ?Sized,

source§

### impl<T> Error for TryLockError<T>

source§

### impl<T> Error for TrySendError<T>

1.8.0 · source§

### impl<T> Error for Box<T>where T: Error,

source§

### impl<T> Error for ThinBox<T>where T: Error + ?Sized,

source§

### impl<T> Error for SendError<T>

1.52.0 · source§

### impl<T> Error for Arc<T>where T: Error + ?Sized,

source§

### impl<T> Error for PoisonError<T>

source§

### impl<W: Send + Debug> Error for IntoInnerError<W>

source§

### impl<const N: usize> Error for GetManyMutError<N>