El trait Error: la firma de un tipo que dice ser un fallo

Cualquier tipo puede viajar dentro de un Err: un String, un entero, un enum cualquiera. Pero para que tu error se integre en el ecosistema —que lo acepte Box<dyn Error>, que anyhow lo absorba, que las herramientas impriman su cadena de causas— tiene que firmar un contrato: el trait std::error::Error. Ese contrato es sorprendentemente pequeño, apenas un método con cuerpo por defecto, pero sus dos supertraits obligatorios y su método source codifican una teoría completa de qué es un error y para quién habla. Entender qué implica implementarlo es entender qué separa “un valor que resultó estar en un Err” de “un fallo de primera clase”.

Un contrato de tres piezas

La definición del trait, despojada de métodos obsoletos y de APIs aún inestables, cabe en unas líneas:

use std::fmt::{Debug, Display};

pub trait Error: Debug + Display {
    // La causa subyacente, si existe. Por defecto, ninguna.
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        None
    }
}

Lo primero que sorprende es que Error no añade casi nada: no exige un método mensaje(), no impone un código numérico, no fuerza una jerarquía de clases. Lo que hace es componer requisitos que ya existían. Al escribir trait Error: Debug + Display, declara dos supertraits: ningún tipo puede implementar Error sin haber implementado antes Display y Debug. Esa es la carga real del contrato, y no es caprichosa.

• Display es la cara del error para el usuario: una frase legible, sin jerga interna, que explica qué salió mal. Es lo que el programa imprime cuando informa de un fallo.
• Debug es la cara para el programador: el volcado estructural que aparece en un panic! o en un log de diagnóstico. Casi siempre se obtiene con #[derive(Debug)].

Un error, por definición en Rust, es un valor que sabe presentarse a dos públicos. Si no puede hacerlo, no es un error: es solo un dato que casualmente metiste en un Err.

source: el hilo que une las causas

El único método propio del trait es source, y su tipo de retorno merece cada símbolo: Option<&(dyn Error + 'static)>. Devuelve opcionalmente una referencia a otro Error, el que provocó a este. Un error de “no se pudo cargar la configuración” tiene como source el error de “fichero no encontrado” que lo originó; ese, a su vez, podría tener el suyo. source es el eslabón que convierte errores sueltos en una cadena de causalidad.

El cuerpo por defecto devuelve None: un error sin causa subyacente, una hoja del árbol, no necesita hacer nada. Solo implementas source cuando tu error envuelve a otro y quieres que esa procedencia siga siendo accesible.

El detalle fino es el contrato tácito entre Display y source: cada capa describe solo su propio nivel. El Display del error externo dice “no se pudo cargar la configuración”, y no repite el mensaje del fichero no encontrado. Ese mensaje inferior vive en el source, y quien quiera la historia completa la recompone recorriendo la cadena. Duplicar el mensaje de la causa dentro del Display del padre es el error de novato que produce informes como “fallo: fallo: fallo: fichero no encontrado”.

Implementar Error a mano

Reunámoslo todo en un tipo que envuelve un std::io::Error:

use std::error::Error;
use std::fmt;

#[derive(Debug)]
struct ErrorConfig {
    ruta: String,
    causa: std::io::Error,
}

impl fmt::Display for ErrorConfig {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        // Solo su propio nivel: la causa la aporta source, no este mensaje.
        write!(f, "no se pudo leer la configuracion en '{}'", self.ruta)
    }
}

impl Error for ErrorConfig {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        Some(&self.causa) // expone el io::Error subyacente
    }
}

Tres bloques: derive(Debug) cubre un supertrait; el impl Display cubre el otro y redacta el mensaje humano; el impl Error solo redefine source para exponer la causa. Con esto, ErrorConfig ya es un ciudadano de pleno derecho del ecosistema de errores.

Recorrer la cadena es entonces un bucle sobre source:

fn informar(e: &dyn Error) {
    eprintln!("error: {e}");
    let mut actual = e.source();
    while let Some(causa) = actual {
        eprintln!("  causado por: {causa}");
        actual = causa.source();
    }
}

Cada vuelta imprime el Display de un nivel y desciende al siguiente con source, hasta que uno devuelve None. Así se genera el clásico informe “error … causado por … causado por …” que verás producir a anyhow en las lecciones siguientes: no es magia, es este bucle.

flowchart LR
A[ErrorConfig con Display propio] -->|source| B[io Error fichero no encontrado]
B -->|source| C[None fin de la cadena]
A --> D[Display para el usuario]
A --> E[Debug para el programador]
style A fill:#cba6f7,color:#11111b
style B fill:#f38ba8,color:#11111b
style C fill:#89b4fa,color:#11111b
style D fill:#a6e3a1,color:#11111b
style E fill:#a6e3a1,color:#11111b

El porqué del ’static

En dyn Error + 'static, la cota 'static desconcierta al principio. No significa “vive toda la ejecución”: significa que el tipo no contiene referencias prestadas de duración limitada, que es dueño de todo lo que lleva dentro. Esa autonomía es la que permite guardar el error en un Box, moverlo por la pila de llamadas y, sobre todo, aplicarle downcast para recuperar su tipo concreto más tarde. Un error que tomara prestado un fragmento de otro dato no podría sobrevivir al retorno de la función que lo creó; por eso el trait pide errores que no dependan de nadie.