thiserror — the same error type, generated

In Building an error type by hand you wrote Display, an Error impl with source(), and a From for every wrapped error. Every line was mechanical. The variant names drove the Display arms, the wrapping variants drove the source() arms, and each foreign error drove a From. Work that regular is work a macro can do. thiserror is a derive macro that generates exactly those three impls from a few attributes you write on the enum. Clinker uses it for leaf errors like ChannelError, which has the same shape as the hand-written FormatError from the last lesson but a fraction of the code. The reference is docs.rs/thiserror.

Prerequisites

• Building an error type by hand

→

Leads to

• CXL: a staged language

What you’ll be able to do

• Read a thiserror-derived error and map each attribute to the impl it generates.
• Explain what #[error("…")], #[from], and a field named source each produce.
• Predict whether a given derived error gives you a working ? and a working error chain.
• Say why clinker derives ChannelError but hand-writes PipelineError, and write a small derived error of your own.

New terms in this lesson (each is expanded inline where you first need it):

• thiserror: the derive macro that generates an error type’s boilerplate impls.
• #[from]: the attribute that generates a From impl and a source(), so ? converts into your type.

Predict first

✋ Predict first

A thiserror enum has a variant Io(#[from] std::io::Error) with the #[from] attribute on its field. Three things might be generated automatically. Which of these does #[from] give you? (a) a Display message for the variant; (b) an impl From<std::io::Error> so ? converts; (c) a source() that returns the io::Error as the cause. Pick all that apply, then reveal.

Decide on your answer before you open the reveal — committing a guess is what makes it stick.

Reveal the answer

#[from] generates (b) and (c), but not (a).

• It generates impl From<std::io::Error> for the enum (b), wrapping the error in this variant. That is what lets ? convert an io::Error into your type, exactly the conversion you wrote by hand last lesson.
• It also marks that field as the error’s source, so the generated source() returns it (c). One attribute covers both the From and the chain link.

It does not write the Display message (a). That always comes from a separate #[error("…")] attribute on the variant. thiserror keeps the two jobs separate: #[error] controls the human text, #[from] controls conversion and the chain. A variant with #[from] but no #[error] will not compile, because it has no message.

The derived leaf: ChannelError

ChannelError is the error clinker’s channel-file parser returns. It is the thiserror twin of the hand-written FormatError: an I/O-and-parse leaf error, one variant per failure, some wrapping a lower error. Compare the line count to last lesson’s three impls.

clinker-channel ·error.rs ·ChannelError type @19acdcb4

#[derive(Debug, thiserror::Error)]
pub enum ChannelError {
    #[error("I/O error reading channel file: {0}")]
    Io(#[from] std::io::Error),

    #[error("YAML parse error in {path}: {source}")]
    Yaml {
        path: PathBuf,
        source: Box<serde_saphyr::Error>,
    },

    #[error("invalid dotted path `{path}`: {reason}")]
    InvalidDottedPath { path: String, reason: String },
    // ... more variants
}

That enum plus its attributes is the whole type. There is no separate impl Display, no impl Error, no impl From. The derive writes all three. Read it attribute by attribute.

Each attribute, and the impl it generates

What you write	What thiserror generates
#[error("I/O error reading channel file: {0}")]	one Display arm; {0} interpolates the variant’s first field
#[error("YAML parse error in {path}: {source}")]	a Display arm using the named fields path and source
#[from] on Io’s field	impl From<std::io::Error> for ChannelError, plus that field as the error’s source()
a field literally named source (the Yaml variant)	a source() that returns it, no #[source] needed

So Display comes from the #[error("…")] strings, the chain comes from #[from] and from any field named source, and ? works wherever there is a #[from]. The three impls you wrote by hand are all here, generated from declarations instead of typed out. The generated code is identical in behavior; thiserror adds no runtime cost, because the derive runs at compile time and emits ordinary impl blocks.

What it expands to (and it still compiles)

The sandbox below has no thiserror dependency, so it shows the hand-written expansion: what the derive on a small Io(#[from] io::Error) variant produces. This is last lesson’s triad, which is precisely the point. Run it, then reread the ChannelError attributes above and see each one in the code here.

rust // editable

reset ▶ run

use std::fmt;

// Equivalent to:
//   #[derive(Debug, thiserror::Error)]
//   enum Cfg {
//       #[error("I/O error: {0}")]
//       Io(#[from] std::io::Error),
//       #[error("missing key: {key}")]
//       Missing { key: String },
//   }
// Below is exactly what that derive would generate.

#[derive(Debug)]
enum Cfg {
  Io(std::io::Error),
  Missing { key: String },
}

impl fmt::Display for Cfg {                  // from the #[error("…")] strings
  fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
      match self {
          Cfg::Io(e) => write!(f, "I/O error: {e}"),
          Cfg::Missing { key } => write!(f, "missing key: {key}"),
      }
  }
}

impl std::error::Error for Cfg {             // source() from the #[from] field
  fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
      match self {
          Cfg::Io(e) => Some(e),
          Cfg::Missing { .. } => None,
      }
  }
}

impl From<std::io::Error> for Cfg {          // generated by #[from]
  fn from(e: std::io::Error) -> Self { Cfg::Io(e) }
}

fn read_cfg(path: &str) -> Result<String, Cfg> {
  let body = std::fs::read_to_string(path)?; // ? uses the From above
  if body.trim().is_empty() {
      return Err(Cfg::Missing { key: "body".into() });
  }
  Ok(body)
}

fn main() {
  match read_cfg("/no/such/file") {
      Ok(b) => println!("ok: {b}"),
      Err(e) => {
          println!("display: {e}");
          if let Some(cause) = std::error::Error::source(&e) {
              println!("caused by: {cause}");
          }
      }
  }
}

use std::fmt; // Equivalent to: // #[derive(Debug, thiserror::Error)] // enum Cfg { // #[error("I/O error: {0}")] // Io(#[from] std::io::Error), // #[error("missing key: {key}")] // Missing { key: String }, // } // Below is exactly what that derive would generate. #[derive(Debug)] enum Cfg { Io(std::io::Error), Missing { key: String }, } impl fmt::Display for Cfg { // from the #[error("…")] strings fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { match self { Cfg::Io(e) => write!(f, "I/O error: {e}"), Cfg::Missing { key } => write!(f, "missing key: {key}"), } } } impl std::error::Error for Cfg { // source() from the #[from] field fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { match self { Cfg::Io(e) => Some(e), Cfg::Missing { .. } => None, } } } impl From<std::io::Error> for Cfg { // generated by #[from] fn from(e: std::io::Error) -> Self { Cfg::Io(e) } } fn read_cfg(path: &str) -> Result<String, Cfg> { let body = std::fs::read_to_string(path)?; // ? uses the From above if body.trim().is_empty() { return Err(Cfg::Missing { key: "body".into() }); } Ok(body) } fn main() { match read_cfg("/no/such/file") { Ok(b) => println!("ok: {b}"), Err(e) => { println!("display: {e}"); if let Some(cause) = std::error::Error::source(&e) { println!("caused by: {cause}"); } } } }

Why clinker still hand-writes PipelineError

If the derive is this much shorter, why is the top-level PipelineError hand-written? Clinker draws the line on purpose. Leaf and subsystem errors like ChannelError are pure boilerplate, so they derive. PipelineError is the error users read most, and its Display strings are tuned diagnostics worth writing by hand, so it stays manual even though thiserror could shorten it. The rule of thumb the codebase follows: derive the errors nobody reads closely; hand-write the one at the top that everybody does.

Worked → completion → faded

Worked: map a derived error to its impls

Reread the ChannelError block and the attribute table above. For the Io variant, name the three things generated for it: a Display arm from #[error], a From<std::io::Error> from #[from], and a source() returning the wrapped error. That is the worked example: one variant, three generated pieces.

Completion: add the attribute that makes ? work

This thiserror enum (shown, not run) is missing one attribute. The Parse variant wraps a std::num::ParseIntError, but nothing tells thiserror to generate the From for it, so ? on a .parse() call would not compile. Add the one attribute that fixes it.

#[derive(Debug, thiserror::Error)]
enum CountError {
    #[error("no value given")]
    Empty,

    #[error("not a number: {0}")]
    Parse(std::num::ParseIntError),   // <-- needs one attribute on this field
}

💡 Hint 1

#[from] on the wrapped field generates the From impl and marks it as the source. The field becomes Parse(#[from] std::num::ParseIntError).

Show solution

#[derive(Debug, thiserror::Error)]
enum CountError {
    #[error("no value given")]
    Empty,

    #[error("not a number: {0}")]
    Parse(#[from] std::num::ParseIntError),
}

With #[from] added, thiserror generates impl From<std::num::ParseIntError> for CountError, so a function returning Result<_, CountError> can write s.parse()? and let the error convert. The #[error("…")] was already there, so the Display message needed no change.

Faded: write a derived error from a spec

Write a thiserror enum DbError with two variants: Connect, which wraps a std::io::Error and should make ? work on a connect call, and NotFound { id: u32 }, a self-made variant with no cause. Give each a Display message. (You cannot run thiserror in the sandbox; write the source, then check it against the reveal.)

Show solution

#[derive(Debug, thiserror::Error)]
enum DbError {
    #[error("connection failed: {0}")]
    Connect(#[from] std::io::Error),

    #[error("no row with id {id}")]
    NotFound { id: u32 },
}

Connect gets a Display, a From<std::io::Error>, and a source() returning the wrapped error, all from #[error] plus #[from]. NotFound gets only a Display; it has no wrapped error, so no From and no chain. That is the same FormatError-shaped split as last lesson, in a third of the lines.

Apply

Open crates/clinker-channel/src/error.rs and find ChannelError. For one #[from] variant, name the From impl it generates. For the Yaml variant, confirm that its source field is what the generated source() returns. Then open crates/clinker-plan/src/error.rs and confirm that PipelineError has no derive and writes its own Display, Error, and From by hand. You are looking at the two halves of clinker’s deliberate split.

Retrieval checkpoint

✓ Checkpoint

// quick check

A thiserror variant is written Io(#[from] std::io::Error) with no #[error(...)] attribute. What happens?

• It compiles; thiserror invents a default Display message
• It fails to compile, because every variant needs an #[error(...)] for its Display
• It compiles but the variant has no From impl

// quick check

Spaced recall — from Building an error type by hand: which three impls does #[derive(thiserror::Error)] replace?

• Debug, Clone, and PartialEq
• Display, std::error::Error (with source), and From
• Serialize, Deserialize, and Default

// quick check

Why does clinker hand-write PipelineError but derive ChannelError?

• thiserror cannot express an enum as large as PipelineError
• PipelineError's Display strings are user-facing diagnostics worth tuning by hand; ChannelError is boilerplate
• Deriving an error makes it slower at runtime, and PipelineError is on the hot path

// quick check

Two developers describe thiserror. Which statement is the MISCONCEPTION to correct?

• thiserror generates ordinary impl blocks at compile time, with no runtime cost
• thiserror is a runtime library your program calls into to format errors
• #[from] generates both a From impl and the source() link for a variant

You should be able to:

• You can map #[error], #[from], and a `source` field to the impls each generates
• You can say what #[from] gives you (a From impl and a source link) and what it does not (a Display message)
• You can explain why thiserror adds no runtime cost
• You can state clinker's rule for deriving vs hand-writing an error
• You wrote a small thiserror enum from a spec

Verify in the checkout:

grep -n 'thiserror::Error' crates/clinker-channel/src/error.rs
grep -n '#\[from\]' crates/clinker-channel/src/error.rs

Connections

You can now read both halves of clinker’s error story: the hand-written triad and the derived shorthand for it, and the judgment call about which to use where. That closes the error thread. The next lesson turns to CXL, the expression language that runs a formula over every record, and shows how a staged parse-typecheck-eval design catches a bad formula at plan time instead of on row four million.

Prerequisites

• Building an error type by hand

→

Leads to

• CXL: a staged language

Go deeper on the Rust (optional — the crate’s own reference):

• Want every thiserror attribute, including #[source] and transparent errors? Read the docs →

Mark this lesson complete