preserve-error-source

name	preserve-error-source
description	Use when defining a new error variant or wrapping a lower-level error — keep the underlying error's source chain intact.

Preserve Error Source Chains

Rule

When a new error wraps a lower-level error, preserve the source so the chain remains traversable:

• Use thiserror's #[source] attribute (or #[from]) to attach the underlying error.
• For dynamic sources, Box<dyn Error + Send + Sync + 'static>.
• Do not call .to_string() on the source and embed it into the wrapper's message — that breaks Error::source() traversal and destroys structured information.

Why

Tools like anyhow, tracing, and logging walk Error::source() to render full chains and group by root cause. Stringifying the source into the message flattens it to one opaque string — the chain can't be walked and the inner error's fields are gone.

Examples

// Good
#[derive(Debug, thiserror::Error)]
pub enum AccountError {
    #[error("failed to deserialize account storage")]
    StorageDeser(#[source] DeserializationError),

    #[error("failed to load account from {path}")]
    Load { path: PathBuf, #[source] io: io::Error },
}

// Bad: source is stringified, chain is lost
#[derive(Debug, thiserror::Error)]
pub enum AccountError {
    #[error("failed to deserialize account storage: {0}")]
    StorageDeser(String),
}

// Bad: source baked into the message via format!
return Err(AccountError::StorageDeser(format!("{e}")));