thiserror: el boilerplate de errores, derivado

Escribir a mano Display, source y un impl From por variante es correcto pero tedioso, y el tedio invita al error humano. En una librería no puedes renunciar al tipado —tus errores son parte del contrato público que tus usuarios diseccionan con match— así que tampoco puedes escapar hacia Box<dyn Error>. La salida es thiserror: una derive macro que genera todo ese boilerplate a partir de una declaración anotada. No introduce ninguna abstracción nueva, no borra tu tipo, no cuesta un solo ciclo en ejecución: emite exactamente el código que habrías tecleado, pero deducido de unos atributos. Es la herramienta canónica para errores de librería en Rust 2024.

El derive que escribe Display, Error y From

Se añade la dependencia y se anota el enum. La versión vigente en 2026 es la 2:

[dependencies]
thiserror = "2"

use thiserror::Error;

#[derive(Debug, Error)]
pub enum ErrorAlmacen {
    #[error("clave no encontrada: {0}")]
    NoEncontrada(String),

    #[error("cuota superada: {usadas} de {limite} entradas")]
    CuotaSuperada { usadas: usize, limite: usize },

    #[error("fallo de entrada/salida en el disco")]
    Io(#[from] std::io::Error),

    #[error("indice corrupto")]
    Indice(#[source] std::num::ParseIntError),
}

Ese bloque genera, en tiempo de compilación, tres cosas que antes escribías a mano: el impl Display completo (a partir de las cadenas #[error(...)]), el impl std::error::Error (con un source que apunta a los campos marcados), y un impl From<std::io::Error> for ErrorAlmacen (por el #[from]). Tú solo sigues derivando Debug, que thiserror deja en tus manos. El resultado es un enum normal y corriente: se puede match, es exhaustivo, es tu tipo. thiserror no lo envuelve ni lo oculta.

Mensajes, from y source con atributos

Cada atributo tiene un cometido preciso, y conviene no confundirlos:

• #[error("...")] define el Display de esa variante. Dentro de la cadena, {0} interpola el campo posicional cero de una variante-tupla y {usadas} interpola un campo con nombre. Admite también especificadores de formato, como {limite:>4}.
• #[from] sobre un campo hace dos cosas de golpe: genera el impl From de ese tipo hacia tu enum —lo que permite que ? convierta hacia esta variante— e implica #[source], marcando ese campo como la causa. Solo puede haber un tipo por cada #[from]: no puedes tener dos variantes con #[from] std::io::Error, porque generarían dos From en conflicto.
• #[source] marca un campo como la causa (lo expone source) sin generar ninguna conversión. Se usa cuando quieres el hilo de causas pero no quieres que ? convierta automáticamente hacia esa variante.

Para dimensionar el ahorro, compara. El ErrorCarga que escribiste a mano en la lección anterior —dos match y dos From, unas veinte líneas— se colapsa a esto, con idéntico comportamiento:

#[derive(Debug, thiserror::Error)]
enum ErrorCarga {
    #[error("fallo al leer el fichero")]
    Lectura(#[from] std::io::Error),
    #[error("el contenido no es un numero")]
    Formato(#[from] std::num::ParseIntError),
}

Mismo tipo, mismo Display, mismo source, mismas conversiones para ?, un tercio del código y ni una oportunidad de teclear mal un match.

transparent: el caso de reenvío puro

A veces una variante no aporta mensaje propio: es un simple pasamanos hacia otro error, y quieres que su Display y su source sean los del error envuelto, no una capa redundante encima. Para eso está #[error(transparent)]:

#[derive(Debug, thiserror::Error)]
pub enum ErrorApi {
    #[error("la peticion excede el limite de tamano")]
    DemasiadoGrande,

    #[error(transparent)]
    Red(#[from] std::io::Error),
}

La variante Red no inventa una frase: delega Display y source directamente al std::io::Error que contiene. Se usa cuando reexportas el error de una capa inferior sin nada útil que añadir; poner ahí un mensaje genérico como “error de red” solo estorbaría al lector, que prefiere ver el mensaje real del sistema. La regla: transparent exige que la variante tenga exactamente un campo, el que absorbe toda la representación.

flowchart TD
D[Declaras un enum con derive Error] --> M[La macro genera en compilacion]
M --> A[impl Display desde los atributos error]
M --> B[impl Error con source]
M --> C[impl From por cada campo from]
A --> R[Tu tipo sigue siendo un enum normal y matchable]
B --> R
C --> R
style D fill:#cba6f7,color:#11111b
style M fill:#89b4fa,color:#11111b
style R fill:#a6e3a1,color:#11111b