Struct Backtrace 

pub struct Backtrace { /* private fields */ }

A backtrace that tracks error propagation through the call stack.

Backtrace stores a complete history of an error’s journey, including:

• Error messages and type names
• Source code locations (file:line:column)
• Nested error chains

Overview

Unlike std::backtrace::Backtrace which captures the call stack, error2::Backtrace tracks the logical error propagation path through your application, showing where errors were created, converted, and propagated.

Creation

Backtraces are typically created automatically by the #[derive(Error2)] macro:

use error2::prelude::*;

#[derive(Debug, Error2)]
#[error2(display("my error"))]
struct MyError {
    backtrace: Backtrace,
}

Accessing Error Information

Use .error_message() to get a formatted error chain:

use regex::Regex;

if let Err(e) = operation() {
    let msg = e.backtrace().error_message();

    // Full error format with location tracking:
    // TestError: test error
    //     at /path/to/file.rs:128:14
    // std::io::error::Error: file not found

    let re = Regex::new(concat!(
        r"(?s)^.+TestError: test error",
        r"\n    at .+\.rs:\d+:\d+",
        r"\nstd::io::error::Error: file not found$",
    ))
    .unwrap();
    assert!(re.is_match(msg.as_ref()));
}

Location Tracking

The backtrace automatically records the location where an error is first created. To track propagation through your call stack, you must manually call:

• .attach() - Records the current location when an error passes through
• .attach_location() - Records a specific location

When converting errors:

• .context() automatically captures where the conversion happens
• .build() / .fail() automatically captures where the root error is created

These methods use #[track_caller] to capture the caller’s location without manual intervention.

Example with Nested Errors

use std::io;

use error2::prelude::*;
use regex::Regex;

#[derive(Debug, Error2)]
pub enum ConfigError {
    #[error2(display("Failed to read: {path}"))]
    Read {
        path: String,
        source: io::Error,
        backtrace: Backtrace,
    },
}

#[derive(Debug, Error2)]
pub enum AppError {
    #[error2(display("Config error"))]
    Config { source: ConfigError },
}

fn read_config() -> Result<String, ConfigError> {
    std::fs::read_to_string("config.toml").context(Read2 {
        path: "config.toml",
    })
}

fn start_app() -> Result<String, AppError> {
    read_config().context(Config2)
}

if let Err(e) = start_app() {
    let msg = e.backtrace().error_message();

    // Full error chain format:
    // AppError: Config error
    //     at /path/to/file.rs:184:19
    // ConfigError: Failed to read: config.toml
    //     at /path/to/file.rs:178:44
    // std::io::error::Error: No such file or directory (os error 2)

    let re = Regex::new(concat!(
        r"(?s)^.+AppError: Config error",
        r"\n    at .+\.rs:\d+:\d+",
        r"\n.+ConfigError: Failed to read: config\.toml",
        r"\n    at .+\.rs:\d+:\d+",
        r"\nstd::io::error::Error: No such file or directory \(os error 2\)$",
    ))
    .unwrap();
    assert!(re.is_match(msg.as_ref()));
}

Implementations

impl Backtrace

pub fn error_message(&self) -> Box<str>

Returns a formatted string containing the complete error chain.

This method produces a human-readable representation of the entire error history, including all nested errors and their locations.

Examples

use regex::Regex;

if let Err(e) = operation() {
    let msg = e.backtrace().error_message();

    // Full error format with location tracking:
    // TestError: test error
    //     at /path/to/file.rs:197:14
    // std::io::error::Error: file not found

    let re = Regex::new(concat!(
        r"(?s)^.+TestError: test error",
        r"\n    at .+\.rs:\d+:\d+",
        r"\nstd::io::error::Error: file not found$",
    ))
    .unwrap();
    assert!(re.is_match(msg.as_ref()));
}

Trait Implementations

impl Clone for Backtrace

fn clone(&self) -> Backtrace

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Backtrace

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

Formats the value using the given formatter.

impl Hash for Backtrace

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Backtrace

fn cmp(&self, other: &Backtrace) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Backtrace

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Backtrace

fn partial_cmp(&self, other: &Backtrace) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Eq for Backtrace

impl StructuralPartialEq for Backtrace