For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /packs/languages/rust/errors.md.
Quick start

Errors

Use native Result for recoverable failures and ? for propagation.

Typed outcomes

Why

Invalid user input is an expected outcome. A panic hides that contract and can terminate unrelated work.

Rules

  • MUST return Result<Content, Failure> for fallible domain operations. [review]
  • MUST classify failures with enums or another typed contract. [review]
  • MUST propagate Results with ?, matching, or Result combinators. [review]
  • MUST keep authored panic!, unwrap, expect, todo!, and unimplemented! out of production application paths. [review]
  • MUST preserve contextual causes at resource boundaries. [review]
  • MUST avoid using catch_unwind as recoverable application control flow. [review]
  • MUST treat ordinary external failures through the external API's Result contract. [review]
  • MAY use assertions and unchecked fixture extraction in tests when failure should fail that test. [review]

Example

#[derive(Debug, PartialEq)]
pub enum PortFailure {
    InvalidPort,
}

pub fn parse_port(text: &str) -> Result<u16, PortFailure> {
    let port = text.parse::<u16>().map_err(|_| PortFailure::InvalidPort)?;
    if port == 0 {
        return Err(PortFailure::InvalidPort);
    }
    Ok(port)
}

#[test]
fn rejects_invalid_ports_as_values() {
    assert_eq!(parse_port("443"), Ok(443));
    assert_eq!(parse_port("0"), Err(PortFailure::InvalidPort));
    assert_eq!(parse_port("bad"), Err(PortFailure::InvalidPort));
}

[review]

Failure-path tests establish the return contract. Configure Clippy restrictions for panics and unchecked extraction; the compiler alone does not ban them.

Enforcement

Failure-path tests establish the return contract. Configure Clippy restrictions for panics and unchecked extraction; the compiler alone does not ban them.