handling-failures

---
name: handling-failures
description: Use when writing or touching any error path, catch block, fallback, default value, retry, or degraded mode - in any language, any repo. Encodes the no-silent-swallows contract and the fail-loud discipline. Use whenever an exception is about to be caught, a null is about to get a default, or a failure could pass unnoticed, even if the goal is "just make it not crash".
---

# Handling failures

**REQUIRED BACKGROUND:** the `principal-engineering` skill.

## Overview

A swallowed error is a bug with its evidence destroyed. Core contract: **every failure path does exactly one of three things, and all three are loud.** A system that looks healthy while serving wrong data is worse than one that crashes.

## The contract

Every catch and failure path either:

1. **Logs at WARN or ERROR and rethrows**, or
2. **Logs and returns a TYPED failure the caller must handle** (a result type, a sealed error, a status the compiler or contract forces downstream code to acknowledge), or
3. **Logs and enters an explicitly documented degraded mode** (named in the code and its documentation, with something observable saying the system is degraded).

Forbidden, no exceptions:

- Bare catch-and-continue.
- Catch-and-return-default (empty list, null, zero, cached copy) that masks the failure.
- `?? fallback` and its cousins where the fallback hides that the primary failed. A fallback is acceptable only when the absence is ALSO surfaced loudly elsewhere.

## Corollaries

- **A missing required entry fails loud.** Something absent from a registry, config, or catalog is a build or startup failure, never a silent default.
- **Error states are visible.** A workflow must not appear healthy while failing; surface the error state in the UI, the metrics, or the logs someone actually watches.
- **Operator-facing remediation is specific.** "connection failed, check REDIS_URL and whether redis responds to PING" beats "an error occurred".
- **Retries are bounded and observable.**
- **Replays of side-effecting operations are idempotent.**
- **Degraded modes have a bound.** Skip-and-continue needs the explicit threshold where degradation becomes abort, as a named, operator-tunable constant. The guard must exist; its value is a judgment call to make with the owner. An unbounded degraded mode is a slow-motion swallow.
- **On failure paths, observability is part of the minimum**, not gold-plating. The log line, the counter, and the alert ship with the fix; a failure path without them is the silent swallow with better intentions.

## Touching existing swallows

Code you are editing that already swallows: fix it as part of the work, or explicitly flag it as owed with what it hides. Leaving it silently is endorsing it. In review, a NEW silent swallow is an automatic BLOCKER; a pre-existing one you touched and left unflagged is a WARNING against the change.

## Common mistakes

- "It should never happen" as a reason to swallow. Those paths are exactly the ones that need a loud alarm when they do.
- Logging at DEBUG and calling it handled. If nobody sees it in production, it is a swallow with extra steps.
- Catching broad (`Exception`, `catch {}`) to handle narrow. The unexpected failure dies silently beside the expected one.
- A degraded mode nobody documented. Degradation only the author knows about is an outage the operator cannot diagnose.
- Making the test pass by defaulting the failure. The test goes green; the defect graduates to production.