`anyhow` & `thiserror`

19 min read

Writing Display, Debug, Error, and From impls by hand for every error type gets tedious fast. The thiserror and anyhow crates are the community-standard answer: thiserror derives those impls for your library’s typed errors, and anyhow gives applications one ergonomic error type with rich context.

Quick Overview

In TypeScript you throw anything and rarely think about error types — every catch block just gets an Error (or unknown). Rust pushes you to be explicit, and these two crates make that explicitness cheap. Use thiserror when you are writing a library and want callers to be able to match on specific failure variants; use anyhow when you are writing an application and just want to attach context and propagate any error to main. They are designed to work together: a library defines a thiserror enum, and the application that consumes it wraps everything in anyhow.

Note: This file covers the two crates and their current APIs. Defining error types by hand (without thiserror) is covered in Custom Errors and The Error Trait; the ? operator that ties it all together is in The ? Operator; and the higher-level “which one, when?” decision lives in Best Practices.

TypeScript/JavaScript Example

In TypeScript, distinguishing error kinds means subclassing Error (verbose) or — more commonly — tagging plain objects with a discriminant and checking it at the catch site. Adding context usually means re-throwing a new error whose cause points at the original.

1
// A "library" module: it defines its own error kinds so callers can branch.
2
class ConfigError extends Error {
3
  readonly kind: "not-found" | "invalid-port" | "missing-key";
4
  constructor(kind: ConfigError["kind"], message: string, options?: { cause?: unknown }) {
5
    super(message, options);
6
    this.name = "ConfigError";
7
    this.kind = kind;
8
  }
9
}
10

11
function parsePort(raw: string): number {
12
  const port = Number(raw);
13
  if (!Number.isInteger(port)) {
14
    // Re-wrap the low-level reason as `cause` so it isn't lost.
15
    throw new ConfigError("invalid-port", "invalid port number", {
16
      cause: new TypeError(`'${raw}' is not an integer`),
17
    });
18
  }
19
  return port;
20
}
21

22
// An "application" layer: it adds context and ultimately just reports.
23
function loadServerConfig(raw: string): number {
24
  try {
25
    return parsePort(raw);
26
  } catch (e) {
27
    // Attaching context = throw a new error pointing at the old one.
28
    throw new Error(`while loading server config from '${raw}'`, { cause: e });
29
  }
30
}
31

32
try {
33
  loadServerConfig("not-a-number");
34
} catch (e) {
35
  if (e instanceof Error) {
36
    // Walk the cause chain manually.
37
    let msg = e.message;
38
    let cur = e.cause;
39
    while (cur instanceof Error) {
40
      msg += `: ${cur.message}`;
41
      cur = cur.cause;
42
    }
43
    console.log(msg); // while loading server config from 'not-a-number': invalid port number: ...
44
  }
45
  // To branch on the *kind*, you must downcast manually:
46
  if (e instanceof ConfigError && e.kind === "invalid-port") {
47
    // handle specifically
48
  }
49
}

Two jobs are tangled together here, and TypeScript gives you no help separating them:

The library job: define distinguishable error kinds (the kind discriminant).
The application job: add human-readable context and walk the cause chain.

Rust splits these cleanly across two crates.

Rust Equivalent

`thiserror` for the library layer

1
use thiserror::Error;
2

3
// One derive generates Display, Error, source(), and From impls.
4
#[derive(Debug, Error)]
5
pub enum ConfigError {
6
    #[error("config file not found at `{0}`")]
7
    NotFound(String),
8

9
    // `#[from]` generates `From<ParseIntError>` AND wires up `source()`.
10
    #[error("invalid port number")]
11
    InvalidPort(#[from] std::num::ParseIntError),
12

13
    // Named fields are interpolated by name in the message string.
14
    #[error("missing required key `{key}`")]
15
    MissingKey { key: String },
16
}
17

18
fn parse_port(raw: &str) -> Result<u16, ConfigError> {
19
    // `?` converts ParseIntError -> ConfigError via the derived `From`.
20
    let port: u16 = raw.parse()?;
21
    Ok(port)
22
}

`anyhow` for the application layer

1
use anyhow::{Context, Result};
2

3
// `anyhow::Result<T>` is shorthand for `Result<T, anyhow::Error>`.
4
fn read_config(path: &str) -> Result<String> {
5
    std::fs::read_to_string(path)
6
        // `.with_context` adds a human-readable layer; the original error
7
        // becomes the *source* beneath it.
8
        .with_context(|| format!("could not read config file `{path}`"))
9
}
10

11
fn main() -> Result<()> {
12
    let _contents = read_config("/no/such/config.toml")?;
13
    Ok(())
14
}

Running that main prints a formatted report and exits non-zero — verified output:

1
Error: could not read config file `/no/such/config.toml`
2

3
Caused by:
4
    No such file or directory (os error 2)

The library code (thiserror) produces a precise enum a caller can match on; the application code (anyhow) attaches context and lets ? and main do the reporting. No hand-written impl Display, no hand-written impl Error, no manual cause-chain walking.

Detailed Explanation

Setting up the crates

Both are ordinary dependencies. From your project directory:

1
cargo add anyhow thiserror

1
      Adding anyhow v1.0.102 to dependencies
2
      Adding thiserror v2.0.18 to dependencies
3
     Locking 7 packages to latest Rust 1.96.0 compatible versions

Note: cargo add is built into Cargo (since 1.62) — you do not need the old cargo-edit crate. This guide uses anyhow 1.x (currently 1.0.102) and thiserror 2.x (currently 2.0.18), the latest stable releases.

`thiserror`: a derive macro, not a runtime

#[derive(Error)] is a procedural macro that, at compile time, writes the impl std::fmt::Display, impl std::error::Error, and any impl From<...> you requested. It adds zero runtime cost and zero runtime dependency — thiserror is purely a code generator. (This is unlike TypeScript decorators, which are real runtime function calls; see Macros for why the two are fundamentally different.)

The pieces of the derive:

#[derive(Debug, Error)] — Error requires Debug (the developer-facing form) and Display (the user-facing form). You always write Debug yourself via derive; thiserror writes Display for you from the #[error(...)] attribute.
#[error("...")] — the format string for Display. Positional tuple fields are {0}, {1}; named struct fields are {field_name}. The same {} formatting and inline-variable syntax you saw in Output applies.
#[from] — on exactly one field of a variant, generates From<ThatType> for YourError so ? can convert automatically, and makes that field the variant’s source().
#[source] — marks a field as the source() (the underlying cause) without generating a From impl. Use it when you want the cause chain but the conversion would be ambiguous (e.g., two variants wrap the same error type).

`anyhow`: one error type to rule the application

anyhow::Error is a single, dynamically-typed error (think of it as a smarter Box<dyn Error>) that:

can be built from any type implementing std::error::Error + Send + Sync + 'static (via ? or .into()),
carries a chain of contexts and causes you can iterate,
formats itself as a clean multi-line report,
can still be downcast back to a concrete type when you need to branch.

The key trait is Context, which adds methods to both Result and Option:

1
use anyhow::{anyhow, bail, ensure, Context, Result};
2

3
fn load_settings(raw: &str) -> Result<u16> {
4
    let timeout: u16 = raw
5
        .parse()
6
        // `.with_context` is LAZY: the closure only runs on the error path.
7
        .with_context(|| format!("failed to parse timeout from {raw:?}"))?;
8

9
    // `ensure!` is like `assert!`, but returns Err instead of panicking.
10
    ensure!(timeout > 0, "timeout must be greater than zero");
11
    Ok(timeout)
12
}
13

14
fn pick(raw: &str) -> Result<u16> {
15
    if raw.is_empty() {
16
        // `bail!` == `return Err(anyhow!(...))`.
17
        bail!("no value provided");
18
    }
19
    // `anyhow!` builds an ad-hoc error from a formatted message.
20
    load_settings(raw).map_err(|e| anyhow!("pick failed: {e}"))
21
}

anyhow!("...") — construct an error from a message (or wrap an existing error).
bail!("...") — early-return that error.
ensure!(cond, "...") — bail unless a condition holds.
.context(msg) — attach an eager message (computed even on the happy path; cheap for string literals).
.with_context(|| msg) — attach a lazy message (the closure runs only when there is actually an error; prefer this when the message requires a format! allocation).

Reading the chain and recovering types

anyhow::Error formats itself three ways, all verified:

1
use anyhow::{Context, Result};
2

3
fn load(raw: &str) -> Result<u16> {
4
    raw.parse::<u16>()
5
        .with_context(|| format!("failed to parse timeout from {raw:?}"))
6
}
7

8
fn main() {
9
    let e = load("abc").unwrap_err();
10
    println!("{e}");    // Display: just the top context
11
    println!("{e:#}");  // alternate: single-line chain joined by ": "
12
    for (i, cause) in e.chain().enumerate() {
13
        println!("[{i}] {cause}"); // iterate top -> bottom
14
    }
15
}

Output:

1
failed to parse timeout from "abc"
2
failed to parse timeout from "abc": invalid digit found in string
3
[0] failed to parse timeout from "abc"
4
[1] invalid digit found in string

Tip: {e} shows only the outermost message; {e:#} (alternate flag) shows the whole chain on one line; and when an anyhow::Error is returned from main, the {e:?} (Debug) form is used automatically, which is the multi-line Caused by: report you saw earlier.

To branch on a specific concrete error after the fact, downcast_ref:

1
use anyhow::Result;
2
use thiserror::Error;
3

4
#[derive(Debug, Error)]
5
#[error("user {id} not found")]
6
struct UserNotFound { id: u32 }
7

8
fn find_user(id: u32) -> Result<String> {
9
    if id != 42 {
10
        return Err(UserNotFound { id }.into()); // typed error -> anyhow::Error
11
    }
12
    Ok("Ada".to_string())
13
}
14

15
fn main() {
16
    if let Err(e) = find_user(7) {
17
        // Recover the original concrete type.
18
        if let Some(unf) = e.downcast_ref::<UserNotFound>() {
19
            println!("typed recovery: missing id {}", unf.id);
20
        }
21
    }
22
}

Output:

1
typed recovery: missing id 7

This is exactly the TypeScript e instanceof ConfigError pattern — except Rust checks the type at runtime through a real type identity, not a fragile prototype chain.

Key Differences

Concern	TypeScript / JavaScript	`thiserror` (libraries)	`anyhow` (applications)
Error type	One `Error` class (or `unknown`)	A concrete enum/struct you define	One opaque `anyhow::Error`
Caller can `match`/branch	`instanceof` + manual discriminant	Yes — on enum variants	Only via `downcast_ref`
Boilerplate	Subclass + set `name`/`cause`	`#[derive(Error)]` writes it all	Nothing to define
Add context	`throw new Error(msg, { cause })`	(caller’s job)	`.context` / `.with_context`
Auto-convert with `?`	`throw` accepts anything	`#[from]` generates `From`	absorbs any `Error` type
Runtime cost	runtime classes	zero (compile-time codegen)	small heap allocation per error
When to use	always (no choice)	public API surface	binaries, scripts, tests, `main`

The decision rule, in one sentence: libraries return thiserror enums so their callers keep choices; applications use anyhow because they are the end of the line and only need to report.

Warning: Do not put anyhow::Error in a public library return type. It erases the variants, so your library’s users can no longer match on what went wrong — they would be stuck with downcast_ref guesses. Reserve anyhow for the application that consumes libraries. More on this split in Best Practices.

A second key difference from TypeScript: in TS, try { ... } catch (e) { switch (e.kind) } is the only tool, and the compiler never checks that you covered every kind. With a thiserror enum, match is exhaustive — add a variant and every match that forgot it stops compiling. That is the same exhaustiveness you get from any Rust enum (see Control Flow).

Common Pitfalls

Pitfall 1: Trying to `match` directly on an `anyhow::Error`

Because anyhow::Error is opaque, you cannot pattern-match its “variants” — it has none.

1
use anyhow::{anyhow, Result};
2

3
#[derive(Debug)]
4
enum MyError { TooBig, TooSmall }
5

6
fn check(n: i32) -> Result<()> {
7
    if n > 100 { return Err(anyhow!("too big")); }
8
    Ok(())
9
}
10

11
fn main() {
12
    if let Err(e) = check(200) {
13
        // does not compile (error[E0308]: mismatched types)
14
        match e {
15
            MyError::TooBig => println!("big"),
16
            MyError::TooSmall => println!("small"),
17
        }
18
    }
19
}

The real compiler error:

1
error[E0308]: mismatched types
2
  --> src/main.rs:15:13
3
   |
4
 4 | enum MyError { TooBig, TooSmall }
5
   |                ------ unit variant defined here
6
...
7
14 |         match e {
8
   |               - this expression has type `anyhow::Error`
9
15 |             MyError::TooBig => println!("big"),
10
   |             ^^^^^^^^^^^^^^^ expected `Error`, found `MyError`

Fix: if you genuinely need to branch on kinds, your error should be a thiserror enum (not anyhow), or you recover the concrete type with e.downcast_ref::<MyError>().

Pitfall 2: Forgetting `#[from]`, then using `?`

A thiserror variant only converts automatically if you ask it to with #[from]. Without it, ? has no From impl to use.

1
use thiserror::Error;
2

3
#[derive(Debug, Error)]
4
enum AppError {
5
    #[error("parse failed")]
6
    Parse(std::num::ParseIntError), // no #[from]
7
}
8

9
fn parse(s: &str) -> Result<i32, AppError> {
10
    let n: i32 = s.parse()?; // tries ParseIntError -> AppError via From
11
    Ok(n)
12
}

The real compiler error:

1
error[E0271]: type mismatch resolving `<i32 as FromStr>::Err == AppError`
2
  --> src/main.rs:10:20
3
   |
4
10 |     let n: i32 = s.parse()?; // tries ParseIntError -> AppError via From
5
   |                    ^^^^^ expected `AppError`, found `ParseIntError`

Fix: add #[from] to the field — Parse(#[from] std::num::ParseIntError) — which generates the From impl that ? needs. (The ?/From relationship is the whole subject of The ? Operator.)

Pitfall 3: `#[from]` on two variants wrapping the same type

You can only have one From<T> impl for a given T. Putting #[from] std::io::Error on two different variants creates conflicting impls and will not compile.

Fix: keep #[from] on at most one variant per source type; mark the others with #[source] and construct them explicitly with .map_err(...). Handling several overlapping error sources is covered in depth in Multiple Error Types.

Pitfall 4: `.context()` that allocates on the happy path

.context(format!("...")) builds the string every time, even when the Result is Ok. On a hot path that is wasted work.

Fix: use .with_context(|| format!("...")) so the format! only runs on the error branch. Reserve the eager .context("literal") for cheap string literals.

Pitfall 5: Expecting `thiserror::Error` to give you a stack trace

Unlike a JavaScript Error, which captures .stack automatically, a thiserror error carries only what you put in its fields — the message and its source(). There is no implicit backtrace.

Fix: for backtraces in applications, enable anyhow’s backtrace feature and run with RUST_BACKTRACE=1; anyhow::Error captures one at creation. For libraries, expose the source() chain and let the application decide.

Best Practices

Libraries → thiserror; applications → anyhow. This is the single most important rule. A crate published to crates.io should expose typed errors; a binary or service should funnel everything into anyhow.
One error enum per module/layer is usually enough. Over-splitting into dozens of tiny enums is as bad as one giant one. Granularity guidance lives in Best Practices.
Prefer #[from] for the common conversions so ? is frictionless, and #[source] when you need the cause chain without an automatic conversion.
Add context at boundaries. Wrap an error with .with_context(...) when it crosses a meaningful layer (“while reading config”, “while connecting to the database”), not on every line.
Use #[error(transparent)] for pass-through variants. It forwards Display and source() to the inner error so you do not invent a redundant message:

1
use thiserror::Error;
2

3
#[derive(Debug, Error)]
4
enum DataError {
5
    #[error("record {index} is malformed")]
6
    Malformed { index: usize },
7

8
    // No message of its own: delegates Display + source to the inner io::Error.
9
    #[error(transparent)]
10
    Io(#[from] std::io::Error),
11
}
12

13
fn first_line(path: &str) -> Result<String, DataError> {
14
    let text = std::fs::read_to_string(path)?; // io::Error -> DataError::Io
15
    let line = text.lines().next().ok_or(DataError::Malformed { index: 0 })?;
16
    Ok(line.to_string())
17
}
18

19
fn main() {
20
    if let Err(e) = first_line("/definitely/missing.txt") {
21
        println!("error: {e}"); // prints the io error's own message
22
    }
23
}

Output:

1
error: No such file or directory (os error 2)

Return anyhow::Result<()> from main in binaries. The ? operator then propagates anything, and Rust prints the Caused by: report and sets a non-zero exit code for free.
anyhow::Error requires Send + Sync + 'static. That is exactly what async runtimes and thread pools need (see Async), so it composes well with tokio. If a hand-rolled error type is not Send + Sync, ? into an anyhow::Result will fail — derive your errors with thiserror and they will satisfy these bounds automatically.

Real-World Example

A two-layer program: a store module is the “library” with a precise thiserror enum, and the application layer uses anyhow to add context, recover specific variants, and report the full chain.

1
// ---- "library" layer: precise, typed errors with thiserror ----
2
mod store {
3
    use thiserror::Error;
4

5
    #[derive(Debug, Error)]
6
    pub enum StoreError {
7
        #[error("user {0} does not exist")]
8
        NotFound(u32),
9

10
        #[error("database is offline")]
11
        Offline,
12

13
        #[error("corrupt row")]
14
        Corrupt(#[from] std::num::ParseIntError),
15
    }
16

17
    #[derive(Debug)]
18
    pub struct User {
19
        pub id: u32,
20
        pub age: u32,
21
    }
22

23
    pub fn fetch(id: u32) -> Result<User, StoreError> {
24
        match id {
25
            0 => Err(StoreError::Offline),
26
            42 => Ok(User { id, age: "thirty".parse()? }), // bad data -> Corrupt
27
            7 => Ok(User { id, age: "30".parse()? }),
28
            _ => Err(StoreError::NotFound(id)),
29
        }
30
    }
31
}
32

33
// ---- "application" layer: anyhow for ergonomic propagation + context ----
34
use anyhow::{Context, Result};
35
use store::StoreError;
36

37
fn greet(id: u32) -> Result<String> {
38
    let user = store::fetch(id)
39
        .with_context(|| format!("while greeting user {id}"))?;
40
    Ok(format!("Hello user {} (age {})", user.id, user.age))
41
}
42

43
fn run() -> Result<()> {
44
    println!("{}", greet(7)?);
45

46
    // Recover a specific typed variant after the fact.
47
    if let Err(e) = greet(99) {
48
        if let Some(StoreError::NotFound(missing)) = e.downcast_ref::<StoreError>() {
49
            println!("(handled) no such user: {missing}");
50
        }
51
    }
52

53
    // A corrupt-row failure carries its source through the context layer.
54
    if let Err(e) = greet(42) {
55
        println!("chain for id 42:");
56
        for cause in e.chain() {
57
            println!("  - {cause}");
58
        }
59
    }
60
    Ok(())
61
}
62

63
fn main() {
64
    if let Err(e) = run() {
65
        eprintln!("fatal: {e:#}");
66
        std::process::exit(1);
67
    }
68
}

Output:

1
Hello user 7 (age 30)
2
(handled) no such user: 99
3
chain for id 42:
4
  - while greeting user 42
5
  - corrupt row
6
  - invalid digit found in string

Notice the three-level chain for id 42: the application’s context (while greeting user 42), the library’s variant message (corrupt row), and the original standard-library cause (invalid digit found in string). Each layer added exactly the information it knew about, and thiserror’s #[from] stitched the source() together automatically.

Exercises

Exercise 1

Difficulty: Beginner

Objective: Replace a hand-written error type with a thiserror enum that carries a source chain.

Instructions: Write a function sum_first_column(text: &str) -> Result<i64, CsvError> that parses the first comma-separated column of each line as an i64 and returns the sum. Define CsvError with thiserror so that (a) an I/O-style variant uses #[from] std::io::Error, and (b) a parse failure variant records the 1-based line number and keeps the original ParseIntError as its source(). Demonstrate the source() chain on bad input.

Solution

1
use thiserror::Error;
2

3
#[derive(Debug, Error)]
4
enum CsvError {
5
    #[error("file error")]
6
    Io(#[from] std::io::Error),
7

8
    #[error("bad number on line {line}")]
9
    Parse {
10
        line: usize,
11
        // #[source] keeps the cause chain WITHOUT generating a From impl
12
        // (we need the line number, so we build this variant manually).
13
        #[source]
14
        source: std::num::ParseIntError,
15
    },
16
}
17

18
fn sum_first_column(text: &str) -> Result<i64, CsvError> {
19
    let mut total = 0i64;
20
    for (i, line) in text.lines().enumerate() {
21
        let first = line.split(',').next().unwrap_or("");
22
        let n: i64 = first
23
            .parse()
24
            .map_err(|e| CsvError::Parse { line: i + 1, source: e })?;
25
        total += n;
26
    }
27
    Ok(total)
28
}
29

30
fn main() {
31
    println!("{:?}", sum_first_column("10,a\n20,b")); // Ok(30)
32

33
    let e = sum_first_column("10\nxx").unwrap_err();
34
    println!("{e}");
35
    if let Some(src) = std::error::Error::source(&e) {
36
        println!("  caused by: {src}");
37
    }
38
}

Output:

1
Ok(30)
2
bad number on line 2
3
  caused by: invalid digit found in string

Exercise 2

Difficulty: Intermediate

Objective: Combine a thiserror library error with an anyhow application that recovers a specific variant.

Instructions: Define HttpError (a thiserror struct holding a status: u16). Write fetch(url: &str) -> anyhow::Result<String> that fails with a 404 HttpError wrapped in context. In main (returning anyhow::Result<()>), call fetch, and if the error downcasts to an HttpError with status 404, treat it as recoverable (print a message and return Ok(())); otherwise propagate it.

Solution

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

4
#[derive(Debug, Error)]
5
#[error("HTTP {status}")]
6
struct HttpError {
7
    status: u16,
8
}
9

10
fn fetch(url: &str) -> Result<String> {
11
    if url.is_empty() {
12
        return Err(HttpError { status: 400 }.into());
13
    }
14
    // Simulate a 404, with a context layer describing the request.
15
    Err(HttpError { status: 404 }).context(format!("requesting {url}"))
16
}
17

18
fn main() -> Result<()> {
19
    match fetch("https://example.com/x") {
20
        Ok(body) => println!("{body}"),
21
        Err(e) => {
22
            // Recover the concrete typed error to decide if it is recoverable.
23
            if let Some(h) = e.downcast_ref::<HttpError>() {
24
                if h.status == 404 {
25
                    println!("not found (recovered, status {})", h.status);
26
                    return Ok(());
27
                }
28
            }
29
            return Err(e); // any other error propagates and is reported by main
30
        }
31
    }
32
    Ok(())
33
}

Output:

1
not found (recovered, status 404)

Exercise 3

Difficulty: Advanced

Objective: Use downcast_ref on an anyhow::Error to implement retry logic that depends on the underlying library error variant.

Instructions: Build an api module with thiserror enum ApiError having variants RateLimited { retry_after_secs: u64 }, BadRequest(#[from] std::num::ParseIntError), and Server { code: u16 }, plus fn call(attempt: u32) -> Result<u32, ApiError> that returns RateLimited on attempt 0, succeeds on attempt 1, and returns a Server error otherwise. In the application, write call_with_retry() -> anyhow::Result<u32> that loops up to 3 attempts: on each error, add context, then downcast_ref::<ApiError>(); if it is RateLimited, log and retry; otherwise propagate. On the final failure, print the full chain().

Solution

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

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

9
        #[error("bad request")]
10
        BadRequest(#[from] std::num::ParseIntError),
11

12
        #[error("server error {code}")]
13
        Server { code: u16 },
14
    }
15

16
    pub fn call(attempt: u32) -> Result<u32, ApiError> {
17
        match attempt {
18
            0 => Err(ApiError::RateLimited { retry_after_secs: 2 }),
19
            1 => Ok("123".parse::<u32>()?), // succeeds
20
            _ => Err(ApiError::Server { code: 500 }),
21
        }
22
    }
23
}
24

25
use anyhow::{Context, Result};
26
use api::ApiError;
27

28
fn call_with_retry() -> Result<u32> {
29
    for attempt in 0..3 {
30
        match api::call(attempt).context("calling upstream API") {
31
            Ok(v) => return Ok(v),
32
            Err(e) => match e.downcast_ref::<ApiError>() {
33
                Some(ApiError::RateLimited { retry_after_secs }) => {
34
                    println!("rate limited, would sleep {retry_after_secs}s; retrying");
35
                    continue;
36
                }
37
                _ => return Err(e), // non-retryable: propagate with context intact
38
            },
39
        }
40
    }
41
    anyhow::bail!("exhausted retries")
42
}
43

44
fn main() {
45
    match call_with_retry() {
46
        Ok(v) => println!("got {v}"),
47
        Err(e) => {
48
            eprintln!("failed: {e:#}");
49
            for cause in e.chain() {
50
                eprintln!("  - {cause}");
51
            }
52
        }
53
    }
54
}

Output:

1
rate limited, would sleep 2s; retrying
2
got 123

anyhow & thiserror

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

thiserror for the library layer

anyhow for the application layer

Detailed Explanation

Setting up the crates

thiserror: a derive macro, not a runtime

anyhow: one error type to rule the application

Reading the chain and recovering types

Key Differences

Common Pitfalls

Pitfall 1: Trying to match directly on an anyhow::Error

Pitfall 2: Forgetting #[from], then using ?

Pitfall 3: #[from] on two variants wrapping the same type

Pitfall 4: .context() that allocates on the happy path

Pitfall 5: Expecting thiserror::Error to give you a stack trace

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1

Exercise 2

Exercise 3

`anyhow` & `thiserror`

`thiserror` for the library layer

`anyhow` for the application layer

`thiserror`: a derive macro, not a runtime

`anyhow`: one error type to rule the application

Pitfall 1: Trying to `match` directly on an `anyhow::Error`

Pitfall 2: Forgetting `#[from]`, then using `?`

Pitfall 3: `#[from]` on two variants wrapping the same type

Pitfall 4: `.context()` that allocates on the happy path

Pitfall 5: Expecting `thiserror::Error` to give you a stack trace