Struct Error 

pub struct Error { /* private fields */ }

An error type that wraps an inner type-erased boxed std::error::Error or an Exn frame.

In that, it’s similar to anyhow, but with support for tracking the call site and trees of errors.

Native error sources

Error::from_error() retains the concrete error and its native source() chain. Use Error::downcast_any_ref() or Error::iter_errors() to inspect the original types, including sources within nested Error values. This also applies when the auto-chain-error feature is enabled.

The auto-chain-error feature

If it’s enabled, this type is merely a wrapper around ChainedError. This happens automatically so applications that require this don’t have to go through an extra conversion.

When both the tree-error and auto-chain-error features are enabled, the tree-error behavior takes precedence and this type uses the tree-based representation.

Implementations

impl Error

Utilities

pub fn error(&self) -> &(dyn Error + 'static)

Return the error stored at this error boundary.

This can be a classification marker hidden from Self::iter_errors(), and is distinct from Self::probable_cause().

impl Error

pub fn from_error(error: impl Error + Send + Sync + 'static) -> Self

Create a new instance representing the given error.

pub fn from_boxed(error: Box<dyn Error + Send + Sync + 'static>) -> Self

Create a new instance representing an already boxed error.

impl Error

pub fn iter_errors(&self) -> impl Iterator<Item = &(dyn Error + 'static)> + '_

Lazily visit stored errors and native sources in logical breadth-first order, expanding nested crate::Error values.

The stored error is first unless it is a classification marker. A frame’s native source precedes its explicitly raised children. Concrete error types remain available for downcasting, except for classification markers, which are always transparent to traversal. Use Self::classify() to inspect classifications.

pub fn iter_errors_with_locations( &self, ) -> impl Iterator<Item = DisplaySource<'_>> + '_

Visit the same errors as Self::iter_errors(), with caller locations for explicitly raised frames. The first real source beneath transparent classification markers inherits their frame’s location; other native sources have no caller location of their own. DisplaySource can render either representation.

pub fn downcast_any_ref<T: Error + 'static>(&self) -> Option<&T>

Find the first diagnostic error that downcasts to T in logical breadth-first order. Classification markers are omitted, as in Self::iter_errors().

pub fn probable_cause(&self) -> &(dyn Error + 'static)

Follow the unique causal path to a leaf or aggregate, as in crate::exn::Frame::probable_cause().

Classification markers are always transparent to selection. Nested error graphs and explicitly raised children both participate, so a selected boundary at a branch is not replaced by one of its nested causes. If selection stays at the root, return the stored error, including a classification-only root.

pub fn metadata(&self) -> impl Iterator<Item = &Metadata> + '_

Visit the non-empty Metadata dictionaries of crate::Message contexts in error traversal order. Dictionaries remain separate. Functions returning metadata document the keys in each context.

To match a class and values on the same message, use Self::classify() and Classification::error() instead of combining independent classification and metadata searches.

pub fn classify(&self) -> Classifications<'_>

Return all known classifications in the same logical breadth-first order as Self::iter_errors().

Unknown errors are omitted. Classifications aren’t deduplicated because distinct errors may independently have the same meaning. Each item retains the classified error for downcasting and origin inspection.

pub fn is_retryable(&self) -> bool

Return true if any stored error or native source has an explicit crate::Class::Retryable classification.

crate::Message and crate::ClassificationMarker can supply this classification. Nested crate::Error values are inspected recursively. Unlike Self::can_retry(), this does not infer retryability from I/O error kinds.

pub fn is_resource_exhausted(&self) -> bool

Return true if any stored error or native source reports resource exhaustion.

This recognizes messages or markers with crate::Class::ResourceExhaustion, std::collections::TryReserveError, and std::io::ErrorKind::OutOfMemory, including within nested crate::Error values.

pub fn can_retry(&self) -> bool

Return true if any stored error, or an error in its source() chain, is:

• classified as crate::Class::Retryable, or
• classified as crate::Class::Io with kind Interrupted or TimedOut.

Nested crate::Error values are inspected recursively. false only means that no known retryable error was found; it does not guarantee that retrying cannot succeed.

pub fn can_retry_lenient(&self) -> bool

Apply Self::can_retry(), also accepting std::io::Error with kind UnexpectedEof, OutOfMemory, BrokenPipe, AddrInUse, ConnectionAborted, ConnectionReset, or ConnectionRefused.

This applies a more lenient policy than Self::can_retry. Nested crate::Error values are inspected recursively. false only means that no known retryable error was found; it does not guarantee that retrying cannot succeed.

pub fn is_corrupted(&self) -> bool

Return true if malformed or internally inconsistent data caused the failure.

pub fn is_not_found(&self) -> bool

Return true if a requested resource was not found.

pub fn is_validation(&self) -> bool

Return true if invalid input caused the failure.

Trait Implementations

impl Debug for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for Error

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

Return the first source of an Exn error, or the source of a boxed error.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

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.

impl<E> From<Exn<E>> for Error

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

fn from(err: Exn<E>) -> Self

Converts to this type from the input type.

impl From<TestError> for Error

fn from(error: TestError) -> Self

Converts to this type from the input type.

impl PartialEq<&str> for Error

fn eq(&self, other: &&str) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<String> for Error

fn eq(&self, other: &String) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<str> for Error

fn eq(&self, other: &str) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.