Skip to content

C0005 panic-in-library

Rule: Library code returns errors for what can fail and says why where it panics.

Code C0005 (stable, never reused)
Id panic-in-library
Category code
Source spirit_level
Fix by hand

Level per tier

Tier Level Reason
small off
small-workspace off
medium warn a library returns errors for what can fail and says why where it panics; warn until tpm_cli, wire_weaver and embedded_bedrock are under 50 findings each, then deny
big warn a library returns errors for what can fail and says why where it panics; warn until tpm_cli, wire_weaver and embedded_bedrock are under 50 findings each, then deny
ai off
embedded deny a service module (LED, log, telemetry) never reaches the panic handler in release: the whole MCU resets for it
ui off
egui off
units-strict off
units-paranoid off

Parameters

Name Type Default Meaning
methods list of strings ["unwrap"] methods that panic on None or Err without saying why
macros list of strings ["panic", "todo", "unimplemented"] macros that panic
bare-macros list of strings ["unreachable"] macros that count only without a message
test-files list of strings ["**/*_tests.rs"] files of test code by name, relative to the crate, besides tests/, benches/, examples/ and #[cfg(test)] modules
classes list of strings [] task classes ([embedded.classes]) whose modules are checked in every crate, binaries included, instead of library code
max integer 0 panicking calls allowed per crate before each is reported

Why

A library that panics where something can fail takes its caller down: a server, a GUI, an agent's long run. An error of operation (a value from outside, I/O, a peer) is a Result the caller decides about. A broken invariant is a panic, and the panic says why the case cannot happen:

Written Counted
.unwrap() yes: it says nothing about why it cannot fail
.expect("8 bytes sliced") no: the reason is read at the site
panic!, todo!, unimplemented! yes
unreachable!() yes
unreachable!("handled before load") no
assert!(cond, "message") no: an invariant check (see assert-message, compound-assert)

Binaries (src/main.rs, src/bin/) and test code are not checked: tests/, benches/, examples/, #[cfg(test)] modules and items, and files named like test code (test-files, *_tests.rs by default). .lock().unwrap() is left to lock-unwrap: a poisoned lock panics on purpose.

Without types, .unwrap() on anything counts, including types where it cannot panic in practice; the parameter max sets how many a crate may have before each is reported.

In firmware the module's task class decides, not the crate kind. The embedded tier sets classes = ["service"]: every module that [embedded.classes] puts in service is checked, in binaries too, with expect, unreachable! and assert! counted as well, since a service module never reaches the panic handler in release.

How to fix

  • A value from outside or an operation that can fail: return an error the caller can handle.
  • A case that cannot happen: .expect("why it cannot fail") or unreachable!("why"); better, a type that makes it impossible (NonZeroU8, an enum, a checked constructor).
  • In a service module: debug_assert!, count the miss (cnt!) and fall back (skip the sample, clamp, reset the task's own state).

Configure

[lints.panic-in-library]
level = "deny"
methods = ["unwrap"]
macros = ["panic", "todo", "unimplemented"]
bare-macros = ["unreachable"]
test-files = ["**/*_tests.rs"]
classes = []
max = 0
reason = "why this project wants it at this level"

Allow one finding in the code with // spirit-level: allow(panic-in-library) <reason> (waivers); the code works there too, as in [lints.C0005].