Trait Error

trait Error: Debug + Display

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: &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: &Self) -> &str
if let Err(e) = "xc".parse::<u32>() {
    // Print `e` itself, no need for description().
    eprintln!("Error: {e}");
}

fn cause(self: &Self) -> Option<&dyn Error>
fn provide<'a>(self: &'a Self, request: &mut Request<'a>)

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

# #![feature(error_generic_member_access)]
# use core::fmt;
# use core::error::Request;
# #[derive(Debug)]
struct MyError {
    source: Error,
}
# #[derive(Debug)]
# struct Error;
# impl fmt::Display for Error {
#     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
#         write!(f, "Example Source Error")
#     }
# }
# impl fmt::Display for MyError {
#     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
#         write!(f, "Example Error")
#     }
# }
# impl std::error::Error for 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
    }
}

Implementors