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.

In tree mode, standard source() traversal prefers the stored error’s native source; otherwise it follows the first explicitly raised child. Nonleaf explicit children are exposed through owning source boundaries so traversal retains their descendants. These boundaries display only their current diagnostic, including with alternate Display, while explicit leaves and native sources retain their raw concrete payloads. Raw standard-source downcasts can thus encounter wrappers; use Error::downcast_any_ref() or Error::iter_errors() for typed inspection of the complete tree. Standard traversal follows one path, not every branch; use Exn::into_chain() for a flattened source chain.

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.

With auto-chain-error, Debug reports the complete diagnostic chain, so returning Result from main() retains the underlying causes. Caller locations are printed only with the error-print-location feature, including for errors returned from main(). Alternate Debug ({error:#?}) omits them. Normal Display shows the root diagnostic; alternate Display ({error:#}) joins the complete chain with : and omits locations, suitable for single-line error messages.

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 into_exn(self) -> Exn

Recover the exception tree for internal processing, preserving its errors, causes, and caller locations.

The tree representation reuses its frame allocation. This also reconstructs explicitly raised frames when auto-chain-error is enabled. Native sources remain owned by their errors and do not become child frames. Use crate::Exn::into_error() to return to a public boundary.

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; use Self::metadata_merged() to combine them. 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 metadata_merged(&self) -> Metadata

Clone all Self::metadata() dictionaries into one owned dictionary.

Later values in logical breadth-first error traversal order replace earlier values with the same key. Thus, more specific causes override their enclosing contexts. For independent causes, the later-visited cause wins; merging does not retain which context supplied a value. Use Self::metadata() instead when that distinction matters. An error without metadata yields an empty dictionary.

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 dominant_class(&self) -> Option<Class>

Return the highest-precedence class found anywhere in the error tree.

This selects the smallest crate::Class according to its recovery precedence, independently of traversal order. Native sources and nested crate::Error values are inspected too. Return None if no known classification is found. Other classes remain observable through Self::classify(); choosing a dominant class does not make their recovery needs ignorable.

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
• a std::io::Error 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. Explicit crate::Class::Cancelled anywhere in the error tree returns false, even alongside retryable causes. A true result does not establish that repeating side effects is safe.

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. Explicit crate::Class::Cancelled anywhere in the error tree returns false. Otherwise false only means no known retryable error was found; true does not establish retry safety.

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_cancelled(&self) -> bool

The caller requested cancellation; stop rather than retry.

pub fn is_permission_denied(&self) -> bool

Authorization or permissions are insufficient; obtain authorization or change permissions.

pub fn is_unauthenticated(&self) -> bool

Credentials are missing or rejected; obtain or refresh credentials.

pub fn is_conflict(&self) -> bool

Current state conflicts with the operation; refresh or reconcile state before retrying.

pub fn is_unsupported(&self) -> bool

A required capability is unsupported; switch implementation, format, protocol, or strategy.

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<Message> for Error

fn from(err: Message) -> Self

Raise the message at the caller’s location, including when converted with .into() or ?. When used as a function pointer, caller tracking stops at the pointer’s invocation shim; use a closure such as |message| message.raise() to capture a location in the calling code.

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 !=.