The Error-Propagation Pattern

20 min read

Most Rust error code follows one repeating shape: each layer defines (or wraps) a typed error, the ? operator carries failures upward by converting them through the From trait, and the outermost layer either reports or recovers. This file is about that architecture — how to layer errors, how ? + From glue the layers together, and the discipline of using thiserror inside libraries while reaching for anyhow at application edges.

Quick Overview

In TypeScript an exception is thrown once and travels up the whole call stack untouched until some catch happens to grab it. Rust has no exceptions: a failing function returns Result<T, E>, and every caller must visibly decide to handle it or pass it along. The ? operator makes “pass it along” a one-character act, and because ? converts the error type via From on the way out, you can give each layer its own error type that wraps the layer beneath it.

The error-propagation pattern is the convention that emerges from this: thiserror for typed, matchable errors in libraries; anyhow for context-rich, opaque errors at the application edge; ? + From to move between layers. This is the design-pattern view; for the underlying mechanics (the Result type, the ? operator, defining custom errors) see Section 08: Error Handling.

Note: This page assumes you already know what Result, ?, and a custom error enum are. If not, read The ? Operator and Custom Errors first, then come back for the architecture.

TypeScript/JavaScript Example

A realistic data-access stack in TypeScript: a low-level line parser, a repository on top of it, and an application handler at the edge. Errors are thrown and bubble through every layer implicitly.

1
// --- Lowest layer: parse a "key=value" record line ---
2
class ParseError extends Error {
3
  constructor(
4
    public line: number,
5
    public raw: string,
6
    options?: { cause?: unknown },
7
  ) {
8
    super(`line ${line}: malformed record '${raw}'`, options);
9
    this.name = "ParseError";
10
  }
11
}
12

13
function parseLine(lineNo: number, raw: string): { id: number; score: number } {
14
  const [idPart, scorePart] = raw.split("=");
15
  if (scorePart === undefined) throw new ParseError(lineNo, raw);
16
  const id = Number(idPart);
17
  const score = Number(scorePart);
18
  if (!Number.isInteger(id) || !Number.isInteger(score)) {
19
    throw new ParseError(lineNo, raw, {
20
      cause: new TypeError("not an integer"),
21
    });
22
  }
23
  return { id, score };
24
}
25

26
// --- Middle layer: a repository over a file ---
27
class RepoError extends Error {
28
  constructor(message: string, options?: { cause?: unknown }) {
29
    super(message, options);
30
    this.name = "RepoError";
31
  }
32
}
33

34
function find(path: string, wanted: number): { id: number; score: number } {
35
  let contents: string;
36
  try {
37
    contents = require("node:fs").readFileSync(path, "utf8");
38
  } catch (e) {
39
    // Re-wrap to add a layer of meaning. The original becomes `cause`.
40
    throw new RepoError(`could not read store file '${path}'`, { cause: e });
41
  }
42
  const lines = contents.split("\n").filter((l) => l.length > 0);
43
  for (let i = 0; i < lines.length; i++) {
44
    const rec = parseLine(i + 1, lines[i]); // ParseError propagates untyped
45
    if (rec.id === wanted) return rec;
46
  }
47
  throw new RepoError(`no record found for id ${wanted}`);
48
}
49

50
// --- Application edge: report or recover ---
51
try {
52
  const rec = find("store.txt", 2);
53
  console.log(`found: ${JSON.stringify(rec)}`);
54
} catch (e) {
55
  // What KIND of error is this? You must reconstruct that by inspection.
56
  if (e instanceof RepoError) console.error(`repo failure: ${e.message}`);
57
  else if (e instanceof ParseError) console.error(`bad data at line ${e.line}`);
58
  else throw e; // unknown — re-throw
59
}

Two things to notice, because Rust inverts both:

Propagation is invisible. parseLine throws and the exception silently skips through find’s body — nothing in find’s signature mentions that it can fail with a ParseError. The type system does not track it.
The error type is erased at the boundary. Every catch receives unknown; to branch on the failure you re-discover its type with instanceof. If a refactor changes what find can throw, no compiler tells the caller.

Rust Equivalent

The same three layers. Each has a typed error; ? converts as it propagates; the edge uses anyhow to add context and report.

1
// ===== A "library" with layered, typed errors (thiserror) =====
2
mod store {
3
    use thiserror::Error;
4

5
    // Lowest layer: parsing one record line.
6
    #[derive(Debug, Error)]
7
    pub enum ParseError {
8
        #[error("line {line}: expected `key=value`, got `{raw}`")]
9
        Malformed { line: usize, raw: String },
10
        #[error("line {line}: invalid number")]
11
        BadNumber {
12
            line: usize,
13
            #[source]
14
            source: std::num::ParseIntError,
15
        },
16
    }
17

18
    // Middle layer: the repository. It WRAPS lower-layer errors instead of
19
    // leaking them, so callers see one coherent error type.
20
    #[derive(Debug, Error)]
21
    pub enum RepoError {
22
        // `#[from]` derives `From<std::io::Error>` and wires up `source()`.
23
        #[error("could not read store file")]
24
        Io(#[from] std::io::Error),
25

26
        // No `#[from]` here: we want to attach the file path at THIS layer,
27
        // so we wrap ParseError as a `#[source]` and build the variant by hand.
28
        #[error("malformed store file `{path}`")]
29
        Parse {
30
            path: String,
31
            #[source]
32
            source: ParseError,
33
        },
34

35
        #[error("no record found for id {0}")]
36
        NotFound(u64),
37
    }
38

39
    #[derive(Debug)]
40
    pub struct Record {
41
        pub id: u64,
42
        pub score: i64,
43
    }
44

45
    fn parse_line(line_no: usize, raw: &str) -> Result<Record, ParseError> {
46
        let (id_part, score_part) = raw.split_once('=').ok_or(ParseError::Malformed {
47
            line: line_no,
48
            raw: raw.to_string(),
49
        })?;
50
        let id = id_part
51
            .trim()
52
            .parse()
53
            .map_err(|source| ParseError::BadNumber { line: line_no, source })?;
54
        let score = score_part
55
            .trim()
56
            .parse()
57
            .map_err(|source| ParseError::BadNumber { line: line_no, source })?;
58
        Ok(Record { id, score })
59
    }
60

61
    pub fn find(path: &str, wanted: u64) -> Result<Record, RepoError> {
62
        // `?` converts io::Error -> RepoError::Io automatically (via #[from]).
63
        let contents = std::fs::read_to_string(path)?;
64
        for (i, line) in contents.lines().enumerate() {
65
            // Add the path as context when crossing the parse -> repo boundary.
66
            let rec = parse_line(i + 1, line).map_err(|source| RepoError::Parse {
67
                path: path.to_string(),
68
                source,
69
            })?;
70
            if rec.id == wanted {
71
                return Ok(rec);
72
            }
73
        }
74
        Err(RepoError::NotFound(wanted))
75
    }
76
}
77

78
// ===== The "application" edge (anyhow) =====
79
use anyhow::{Context, Result};
80

81
fn run() -> Result<()> {
82
    // Write a store file with one deliberately broken line.
83
    let path = std::env::temp_dir().join("probe_store.txt");
84
    std::fs::write(&path, "1=100\n2=oops\n3=300\n")?;
85
    let path = path.to_string_lossy().into_owned();
86

87
    // `?` converts RepoError -> anyhow::Error (anyhow accepts any std error).
88
    // `.with_context` adds a human-readable layer at the edge.
89
    let rec = store::find(&path, 2)
90
        .with_context(|| format!("looking up record 2 in `{path}`"))?;
91
    println!("found id={} score={}", rec.id, rec.score);
92
    Ok(())
93
}
94

95
fn main() {
96
    if let Err(err) = run() {
97
        // `{:#}` prints the whole context chain on one line.
98
        eprintln!("Error: {err:#}");
99
        eprintln!("---- debug ----");
100
        // `{:?}` (Debug) prints the chain stacked, plus a backtrace section.
101
        eprintln!("{err:?}");
102
        std::process::exit(1);
103
    }
104
}

Add the two dependencies in your probe project:

1
cargo add thiserror anyhow

Running it produces (the temp path will differ on your machine):

1
Error: looking up record 2 in `/tmp/probe_store.txt`: malformed store file `/tmp/probe_store.txt`: line 2: invalid number: invalid digit found in string
2
---- debug ----
3
looking up record 2 in `/tmp/probe_store.txt`
4

5
Caused by:
6
    0: malformed store file `/tmp/probe_store.txt`
7
    1: line 2: invalid number
8
    2: invalid digit found in string

That four-level chain — edge context → repo layer → parse layer → the raw ParseIntError — is assembled for free because every layer wired its lower-level cause in as a source.

Detailed Explanation

? is From-powered propagation. When you write let x = fallible()?;, Rust desugars it to roughly:

1
// What `let contents = std::fs::read_to_string(path)?;` expands to:
2
let contents = match std::fs::read_to_string(path) {
3
    Ok(value) => value,
4
    // `From::from` converts the error to the function's declared error type.
5
    Err(e) => return Err(From::from(e)),
6
};

So ? does two jobs: it early-returns on Err, and it calls From::from to convert the inner error into the function’s return error type. That single conversion step is the entire mechanism behind layered errors — you do not have to convert manually as long as a From impl exists.

#[from] generates the From impl for you. In the example, #[error("...")] Io(#[from] std::io::Error) makes thiserror emit impl From<std::io::Error> for RepoError. That is why std::fs::read_to_string(path)? inside find “just works” — ? finds the generated From and uses it. The same derive also implements Error::source() so the io::Error shows up beneath RepoError::Io in the cause chain.

When you need to add data at the boundary, use #[source] + map_err. A #[from] conversion is automatic but loses the opportunity to attach context, because From::from only receives the inner error. In find, we want to record which file failed to parse, so we cannot use #[from] for RepoError::Parse; instead we map_err(|source| RepoError::Parse { path: ..., source }). The #[source] attribute tells thiserror “this field is the cause,” so it still appears in the chain.

anyhow at the edge. run returns anyhow::Result<()> (an alias for Result<(), anyhow::Error>). anyhow::Error implements From<E> for any E: std::error::Error + Send + Sync + 'static, which is why store::find(...)? works even though find returns a RepoError and run returns an anyhow::Error. .with_context(...) wraps the error in a new layer whose message is the closure’s output and whose source is the original — exactly like throwing a new Error with { cause: e } in TypeScript, but type-checked and zero-boilerplate.

The closure form with_context(|| ...) is lazy. It only builds the message string on the error path. There is also .context("static message") for cheap, always-allocated context. Prefer with_context when the message needs format!.

Key Differences

Concern	TypeScript / JavaScript	Rust
Propagation	Implicit `throw` skips through every frame	Explicit: `?` at each call site, visible in the signature
What can a function fail with?	Not in the type — `throws` is untracked	In the return type: `Result<T, MyError>`
Carrying errors up	Automatic (exception unwinding)	`?` + a `From` conversion per layer
Branching on error kind	`instanceof` / discriminant at runtime	`match` on an enum, checked at compile time
Adding context	`new Error(msg, { cause })`	`.context(...)` / a wrapping enum variant with `#[source]`
Cause chain	`error.cause` (walk it manually)	`Error::source()` (anyhow/thiserror walk it for you)
Library vs app	Same `Error` everywhere	`thiserror` (typed, matchable) vs `anyhow` (opaque, contextual)

The headline conceptual difference: Rust makes the set of possible failures part of the function’s type. A TypeScript caller cannot tell from a signature whether find throws RepoError, ParseError, or something from fs. A Rust caller reads -> Result<Record, RepoError> and knows exactly what to handle.

The thiserror-vs-anyhow split is the heart of the pattern:

Libraries return thiserror enums. Your consumers may want to recover from specific failures (retry on a timeout, fall back on a cache miss). That requires a concrete, matchable type. An opaque error would force them to parse your error messages — a brittle anti-pattern.
Applications return anyhow::Error. A binary’s main usually just logs the failure and exits non-zero. It does not benefit from a giant hand-written enum that unions every dependency’s error; it benefits from cheap context and a readable cause chain. anyhow gives exactly that.

Tip: A useful mnemonic: “thiserror is for code other code calls; anyhow is for code humans run.” The same crate can do both — a library crate’s internal binary (an example, a small CLI front-end) can use anyhow even while the library API uses thiserror.

Common Pitfalls

Using `?` when no `From` impl connects the two error types

1
#[derive(Debug)]
2
struct AppError(String);
3

4
fn read_count() -> Result<u32, AppError> {
5
    // does not compile (error[E0277]): io::Error has no `From` into AppError
6
    let text = std::fs::read_to_string("data.txt")?;
7
    Ok(text.len() as u32)
8
}
9

10
fn main() {
11
    let _ = read_count();
12
}

The real compiler error:

1
error[E0277]: `?` couldn't convert the error to `AppError`
2
 --> src/main.rs:6:51
3
  |
4
4 | fn read_count() -> Result<u32, AppError> {
5
  |                    --------------------- expected `AppError` because of this
6
5 |     // does not compile (error[E0277]): io::Error has no `From` into AppError
7
6 |     let text = std::fs::read_to_string("data.txt")?;
8
  |                -----------------------------------^ the trait `From<std::io::Error>` is not implemented for `AppError`
9
  |                |
10
  |                this can't be annotated with `?` because it has type `Result<_, std::io::Error>`
11
  |
12
note: `AppError` needs to implement `From<std::io::Error>`
13
 --> src/main.rs:2:1
14
  |
15
2 | struct AppError(String);
16
  | ^^^^^^^^^^^^^^^
17
  = note: the question mark operation (`?`) implicitly performs a conversion on the error value using the `From` trait
18

19
For more information about this error, try `rustc --explain E0277`.

The compiler tells you exactly what is missing: implement From<std::io::Error> for AppError, or (in a library) add a #[from] variant, or (at an app edge) return anyhow::Result instead.

Trying to `match` on an `anyhow::Error`

anyhow::Error is opaque — it has no variants to match. If at some boundary you need to recover from a specific underlying error you wrapped, use downcast_ref:

1
use anyhow::{anyhow, Result};
2
use thiserror::Error;
3

4
#[derive(Debug, Error)]
5
enum DbError {
6
    #[error("row {0} not found")]
7
    NotFound(u64),
8
    #[error("connection lost")]
9
    ConnectionLost,
10
}
11

12
fn fetch(id: u64) -> Result<String> {
13
    Err(anyhow!(DbError::NotFound(id))) // a typed error, carried by anyhow
14
}
15

16
fn main() {
17
    match fetch(42) {
18
        Ok(name) => println!("got {name}"),
19
        Err(err) => {
20
            // You cannot `match err { DbError::... }` — anyhow::Error is opaque.
21
            // Recover the concrete type with downcast_ref:
22
            if let Some(DbError::NotFound(id)) = err.downcast_ref::<DbError>() {
23
                println!("recovered: row {id} was missing (will retry)");
24
            } else {
25
                eprintln!("unhandled: {err:#}");
26
            }
27
        }
28
    }
29
}

Output:

1
recovered: row 42 was missing (will retry)

But notice the friction: you threw away the type by using anyhow, then had to dynamically recover it. That is the signal that this code wanted a thiserror enum, not anyhow. Reach for downcast_ref rarely; if you do it routinely, your boundary should return a typed error.

Putting `anyhow` in a public library API

If your published crate’s functions return anyhow::Result<T>, every consumer is forced to depend on anyhow and loses the ability to handle your failures programmatically. Keep anyhow::Error out of public signatures; expose a thiserror enum instead. The decision tree is covered further in anyhow & thiserror.

Forgetting that `?` returns early — including in the middle of cleanup

Because ? is an early return, a ? that fires before a manual cleanup line will skip that cleanup. Rust’s answer is not “remember to clean up before every ?” but the RAII / Drop pattern: tie cleanup to a value’s scope so it runs no matter how the function exits. See RAII and Drop Guards.

Best Practices

One error type per layer, each wrapping the one below. The parser returns ParseError; the repository returns RepoError that contains a ParseError; the app collapses everything into anyhow::Error. This keeps each layer’s error vocabulary focused.
Use #[from] for pure pass-through, #[source] + map_err when you add data. #[from] is great for “this layer can also fail with the layer below, unchanged.” Switch to #[source] the moment you want to attach context (a path, an ID, a request) at the boundary.

#[error(transparent)] for a variant that should be indistinguishable from its inner error. Use it when a variant exists only to carry a foreign error through without adding any message of its own:

1
use thiserror::Error;
2

3
#[derive(Debug, Error)]
4
#[error("TOML parse error: {0}")]
5
pub struct TomlError(pub String);
6

7
#[derive(Debug, Error)]
8
pub enum ConfigError {
9
    #[error("failed to read config from `{path}`")]
10
    Read {
11
        path: String,
12
        #[source]
13
        source: std::io::Error,
14
    },
15
    // Delegate Display + source entirely to the inner error.
16
    #[error(transparent)]
17
    Toml(#[from] TomlError),
18
    #[error("invalid config: port {0} is out of range (1..=65535)")]
19
    PortOutOfRange(u32),
20
}

Add context at the edge with with_context, not by reformatting the message. .with_context(|| format!("starting server with {path}")) preserves the underlying error as a source; rewriting it as format!("{e}: starting server") flattens the chain and loses structure.

Print {:#} for users, {:?} for logs. anyhow’s alternate Display ({:#}) gives a compact one-line chain; Debug ({:?}) gives the stacked Caused by: list (plus a backtrace when RUST_BACKTRACE=1). For comparison:

1
Display  {}:  initializing the database
2
Alt      {:#}: initializing the database: reading the seed list: No such file or directory (os error 2)
3
---- Debug {:?} ----
4
initializing the database
5

6
Caused by:
7
    0: reading the seed list
8
    1: No such file or directory (os error 2)

Box<dyn Error> is the dependency-free middle ground. Before reaching for anyhow, know that the standard library already lets ? converge many error types into Box<dyn std::error::Error>:
```
1
use std::error::Error;
2

3
fn count_lines(path: &str) -> Result<usize, Box<dyn Error>> {
4
    let text = std::fs::read_to_string(path)?; // io::Error -> Box<dyn Error>
5
    let _first: u32 = text.lines().next().unwrap_or("0").trim().parse()?; // and ParseIntError
6
    Ok(text.lines().count())
7
}
```
Calling count_lines("/no/such/file") yields an Err whose message is No such file or directory (os error 2). It works because every E: Error + 'static converts into Box<dyn Error>. anyhow is essentially this plus context, backtraces, and downcast — but if you cannot add a dependency, Box<dyn Error> at a binary’s main is perfectly idiomatic.

Warning: Do not derive Clone on error types reflexively. Many wrapped errors (like std::io::Error) are not Clone, and forcing it usually means stringifying the cause and losing the chain. Errors are meant to be moved up and consumed once.

Real-World Example

A configuration loader as a small library, consumed by an application main. The library uses a layered thiserror enum (IO, parse via #[from] + transparent, and validation); the binary uses anyhow to add a startup-context layer and let main report. This mirrors how a real service wires config loading to fn main.

1
mod config {
2
    use thiserror::Error;
3

4
    #[derive(Debug, Error)]
5
    pub enum ConfigError {
6
        #[error("failed to read config from `{path}`")]
7
        Read {
8
            path: String,
9
            #[source]
10
            source: std::io::Error,
11
        },
12

13
        // `transparent` makes this variant display exactly like the inner error.
14
        #[error(transparent)]
15
        Toml(#[from] TomlError),
16

17
        #[error("invalid config: port {0} is out of range (1..=65535)")]
18
        PortOutOfRange(u32),
19
    }
20

21
    // Stand-in for a real crate's parse error (e.g. `toml::de::Error`).
22
    #[derive(Debug, Error)]
23
    #[error("TOML parse error: {0}")]
24
    pub struct TomlError(pub String);
25

26
    #[derive(Debug)]
27
    pub struct Config {
28
        pub port: u16,
29
    }
30

31
    pub fn load(path: &str) -> Result<Config, ConfigError> {
32
        let raw = std::fs::read_to_string(path).map_err(|source| ConfigError::Read {
33
            path: path.to_string(),
34
            source,
35
        })?;
36
        // Pretend-parse: expect a single line `port = N`.
37
        let value: u32 = raw
38
            .trim()
39
            .strip_prefix("port = ")
40
            .ok_or_else(|| TomlError(format!("expected `port = N`, got `{}`", raw.trim())))?
41
            .parse()
42
            // `?` converts TomlError -> ConfigError::Toml via the derived #[from].
43
            .map_err(|_| TomlError("port is not a number".into()))?;
44
        if !(1..=65535).contains(&value) {
45
            return Err(ConfigError::PortOutOfRange(value));
46
        }
47
        Ok(Config { port: value as u16 })
48
    }
49
}
50

51
use anyhow::{Context, Result};
52

53
fn main() -> Result<()> {
54
    let path = std::env::temp_dir().join("probe_config.toml");
55
    std::fs::write(&path, "port = 70000\n")?; // out-of-range on purpose
56
    let path = path.to_string_lossy().into_owned();
57

58
    // The library's typed ConfigError flows into anyhow::Error via `?`,
59
    // and we add an application-level context layer.
60
    let cfg = config::load(&path).with_context(|| format!("starting server with `{path}`"))?;
61
    println!("listening on port {}", cfg.port);
62
    Ok(())
63
}

Because main returns anyhow::Result<()>, Rust prints the returned error using anyhow’s formatting and exits with a non-zero status. Real output:

1
Error: starting server with `/tmp/probe_config.toml`
2

3
Caused by:
4
    invalid config: port 70000 is out of range (1..=65535)

The library kept a typed error (a downstream caller could match on ConfigError::PortOutOfRange to suggest a fix), while the binary got a contextual report for free — the pattern, working end to end. This style scales directly to web handlers and database layers; see how it threads through real services in Section 16: Web APIs.

Exercises

Exercise 1: Make `?` work across two source errors

Difficulty: Easy

Objective: Define a single layered error type so a function can use ? over both std::io::Error and a parse failure.

Instructions:

Write fn load_count(path: &str) -> Result<u32, LoadError> that reads a file and parses its trimmed contents into a u32.
Define LoadError with thiserror so the IO failure records the path (as a #[source]) and the parse failure records the offending string.
Make the two fallible steps propagate cleanly. (#[from] cannot record the path — think about why.)

1
use thiserror::Error;
2

3
#[derive(Debug, Error)]
4
enum LoadError {
5
    // TODO: an Io variant that keeps the path + the io::Error source
6
    // TODO: a Parse variant that keeps the bad input string
7
}
8

9
fn load_count(path: &str) -> Result<u32, LoadError> {
10
    /* ??? */
11
}

Solution

1
use thiserror::Error;
2

3
#[derive(Debug, Error)]
4
enum LoadError {
5
    #[error("could not read `{path}`")]
6
    Io {
7
        path: String,
8
        #[source]
9
        source: std::io::Error,
10
    },
11
    #[error("`{0}` is not a valid count")]
12
    Parse(String),
13
}
14

15
fn load_count(path: &str) -> Result<u32, LoadError> {
16
    // `#[from]` would discard the path, so we map_err to attach it here.
17
    let text = std::fs::read_to_string(path).map_err(|source| LoadError::Io {
18
        path: path.to_string(),
19
        source,
20
    })?;
21
    let trimmed = text.trim();
22
    let count = trimmed
23
        .parse()
24
        .map_err(|_| LoadError::Parse(trimmed.to_string()))?;
25
    Ok(count)
26
}
27

28
fn main() {
29
    match load_count("/no/such/file") {
30
        Ok(n) => println!("count = {n}"),
31
        Err(e) => println!("error: {e}"),
32
    }
33
}

Running against a missing file prints:

1
error: could not read `/no/such/file`

Exercise 2: Bridge a library error into an `anyhow` edge with selective recovery

Difficulty: Medium

Objective: Consume a thiserror-based library error at an application edge, recovering from one variant and propagating the other with context.

Instructions:

Given a CacheError enum with Miss(String) and Unavailable variants, write fn handle(key: &str) -> anyhow::Result<String>.
On a cache miss, recover by returning a default value (do not propagate).
On unavailable, attach context and propagate as an anyhow::Error.

Solution

1
use anyhow::{Context, Result};
2
use thiserror::Error;
3

4
#[derive(Debug, Error)]
5
pub enum CacheError {
6
    #[error("cache miss for key `{0}`")]
7
    Miss(String),
8
    #[error("cache backend unavailable")]
9
    Unavailable,
10
}
11

12
fn get(key: &str) -> Result<String, CacheError> {
13
    if key == "warm" {
14
        Ok("hot-value".to_string())
15
    } else {
16
        Err(CacheError::Miss(key.to_string()))
17
    }
18
}
19

20
fn handle(key: &str) -> Result<String> {
21
    match get(key) {
22
        Ok(v) => Ok(v),
23
        // A miss is recoverable: fall back to a default.
24
        Err(CacheError::Miss(_)) => Ok("default-value".to_string()),
25
        // A real outage is fatal at this edge: add context and propagate.
26
        Err(e @ CacheError::Unavailable) => {
27
            Err(e).with_context(|| format!("while serving key `{key}`"))
28
        }
29
    }
30
}
31

32
fn main() -> Result<()> {
33
    println!("{}", handle("warm")?);
34
    println!("{}", handle("cold")?);
35
    Ok(())
36
}

Output:

1
hot-value
2
default-value

The key insight: because the library returns a typed CacheError, the edge can match and decide per-variant. Had get returned anyhow::Result, that branch would have required a fragile downcast_ref.

Exercise 3: Recover a typed error from `anyhow` at the boundary

Difficulty: Medium

Objective: Carry a typed error through anyhow, then recover it at the edge with downcast_ref to drive a retry decision.

Instructions:

Define a RateLimited { retry_after_secs: u64 } error with thiserror.
Write fn call_api() -> anyhow::Result<()> that returns it via anyhow!(...).
In main, recover the concrete RateLimited from the anyhow::Error and print the back-off duration; otherwise print a fatal message.

Solution

1
use anyhow::{anyhow, Result};
2
use thiserror::Error;
3

4
#[derive(Debug, Error)]
5
#[error("rate limited: retry after {retry_after_secs}s")]
6
struct RateLimited {
7
    retry_after_secs: u64,
8
}
9

10
fn call_api() -> Result<()> {
11
    Err(anyhow!(RateLimited { retry_after_secs: 30 }))
12
}
13

14
fn main() {
15
    if let Err(err) = call_api() {
16
        // Recover the concrete type that was wrapped by anyhow.
17
        if let Some(rl) = err.downcast_ref::<RateLimited>() {
18
            println!("backing off for {}s", rl.retry_after_secs);
19
        } else {
20
            eprintln!("fatal: {err:#}");
21
        }
22
    }
23
}

Output:

1
backing off for 30s

This works, but it is the exception, not the rule: if you find yourself downcast_ref-ing routinely, the boundary should expose a typed thiserror enum so callers can match directly — exactly the trade-off this pattern is about.

The Error-Propagation Pattern

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

Key Differences

Common Pitfalls

Using ? when no From impl connects the two error types

Trying to match on an anyhow::Error

Putting anyhow in a public library API

Forgetting that ? returns early — including in the middle of cleanup

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1: Make ? work across two source errors

Exercise 2: Bridge a library error into an anyhow edge with selective recovery

Exercise 3: Recover a typed error from anyhow at the boundary

Using `?` when no `From` impl connects the two error types

Trying to `match` on an `anyhow::Error`

Putting `anyhow` in a public library API

Forgetting that `?` returns early — including in the middle of cleanup

Exercise 1: Make `?` work across two source errors

Exercise 2: Bridge a library error into an `anyhow` edge with selective recovery

Exercise 3: Recover a typed error from `anyhow` at the boundary