Correctness Traps

---
name: correctness-traps
description: Use when writing or reviewing error handling, floating-point math, concurrent code, remote calls, singletons/globals, hot-path data structures, or high-volume log statements
---

# Error and Correctness Traps

## Overview

Common bugs grouped by domain: floats that won't compare equal, retries that hammer a downed service, singletons that wreck testability, and others. **When you write code in one of these domains, stop and run the matching checks before you commit.**

This is a **rigid** skill. Jump to the sub-section that matches what you're writing and run that sub-section's checks.

These checks matter most when code will reach real users in production. In MVPs, prototypes, internal dev tools, and one-off scripts where the architecture is still in flux, prefer the simplest thing that works.

## When to invoke

Invoke when you're about to:

- Add or change error-handling around a call that can fail
- Compare, sum, or accumulate floating-point numbers
- Write concurrent, parallel, or threaded code, or share mutable state between threads
- Call a remote process, web service, database, or another machine
- Introduce a singleton or any globally-shared mutable state
- Choose a data structure or algorithm on a path that runs often or on large inputs
- Add or change log statements that may fire at high volume
- Review code that handles errors, floats, concurrency, remote calls, singletons, or hot-path data structures

### Non-triggers — do NOT invoke for

- Renaming a local variable inside one function
- Adding a docstring to an existing function
- Fixing a typo in a comment
- Formatting-only changes handled by a formatter
- Adjusting a config value in a config file with no logic change
- Skimming code for context without producing findings or edits
- An early-stage MVP or prototype where the architecture is still in flux
- An internal dev tool, debugging endpoint, or one-off script
- Throwaway code expected to be replaced before reaching users

If the change touches one of these domains even slightly, **invoke anyway** — the per-domain check is short and the bugs are not.

## Checks by domain

### Errors (97/21, 97/26, 97/29)

1. **Distinguish business exceptions from technical ones.** A *technical* exception means the system can't proceed — bad arguments, broken DB connection, programming error. Let it bubble to a top-level handler that puts the system in a safe state (rollback, log, alert, friendly user message); the caller can't fix it. A *business* exception is part of the contract — withdrawing from an empty account, booking an unavailable slot — and is an alternative return path the caller is expected to handle. Give them separate types or hierarchies; mixing them blurs the contract. *(Bergh Johnsson, 97/21.)*
2. **Never write the empty `catch`.** `try { ... } catch (...) {}` silently swallows everything. Same for ignoring return codes (`printf`'s return value, `write()`'s short-write count) and pretending `errno` doesn't exist. Example: a service-call wrapper swallows every exception and returns `null`, so every downstream caller has to invent their own theory of what `null` means. Expose erroneous conditions in your interfaces; if handling errors feels onerous, the interface is wrong. *(Goodliffe, 97/26.)*
3. **Don't rely on unexplained magic.** If your change depends on behavior nobody can explain (build picks a DLL by load order, deployment reads an undocumented env var, a job runs because of a side effect in a config file), surface it in your summary to the user before shipping — don't bury the dependency. *(Griffiths, 97/29.)*

### Numerics (97/33)

4. **Never compare floats with `==`.** `0.1 + 0.2 != 0.3` in IEEE 754 — the canonical demonstration. Compare with a tolerance appropriate to the magnitude of the values involved (≈ ε|x|, where ε is machine epsilon — ~1e-7 for `float`, ~1e-16 for `double`).
5. **Watch for catastrophic cancellation.** Subtracting nearly-equal floats promotes roundoff to the most significant digits. Example: solving `x² - 100000x + 1 = 0` directly via the quadratic formula gives a wildly wrong small root because `-b + sqrt(b² - 4)` cancels; compute one root and derive the other from `r1 * r2 = c/a`. Same shape of error appears in any series with alternating signs of similar magnitude.
6. **Don't use float for money.** Use a fixed-point or decimal type. Floats are for scientific calculation where you accept ε-level error; financial code does not accept it. *(Allison, 97/33.)*

### Concurrency & IPC (97/41, 97/57)

7. **Default to message passing over shared mutable state.** When you reach for a lock around shared data, ask first whether the data could be owned by one process/actor that others message. CSP-style designs (Erlang, Go channels, actor frameworks in mainstream languages) sidestep most race / deadlock / livelock bugs by construction. Reserve shared-memory + locks for cases you have measured and understood. *(Winder, 97/57.)*
8. **Count IPCs per user stimulus, not lines of code.** Each remote call is non-trivial latency; sequential calls add. Example: ORM lazy-loading produces 1,000 sequential 10ms DB calls for one page render — minimum 10s response time before any rendering work. Ratios in the thousands appear routinely in slow apps. Apply parsimony (one round-trip carrying the right data), parallelism (overall latency = longest call, not sum), or caching. *(Stafford, 97/41.)*
9. **Retry with backoff and a cap, never in a tight loop.** Example: `while (!call()) call();` against a downed service hammers it the moment it comes back. Exponential backoff, jitter, and a max-retries ceiling are the minimum; idempotency on the server side is what makes retry safe at all.

### Limits & Performance (97/46, 97/89)

10. **Know the complexity of the data structure you picked.** Linked list vs. hash vs. balanced tree on a million items is the difference between snappy and unusable. Pick by access pattern (lookup-heavy → hash; ordered iteration → tree; tiny + cache-friendly → array), not by what's familiar. *(van Winkel, 97/89.)*
11. **Don't recompute invariants inside loops.** Example: `for (i = 0; i < strlen(s); ++i)` — `strlen` runs every iteration, scanning the whole string each time, turning O(n) work into O(n²). Hoist the length out. The same shape applies to repeated DB lookups, repeated config parses, and repeated regex compilations inside hot loops. *(van Winkel, 97/89.)*
12. **Respect the cache hierarchy when it dominates.** Register and L1 are nanoseconds; RAM is ~20ns; disk is ~10ms; network is ~20–100ms — orders of magnitude apart. A "worse" big-O algorithm with a predictable access pattern can beat a "better" one that thrashes cache. When perf matters, **measure** rather than reason from complexity alone. *(Colvin, 97/46.)*

### Globals & Singletons (97/73)

13. **Resist the singleton.** Most singletons encode a single-instance assumption that turns out to be premature, broadcast across the design as hidden coupling. They wreck unit-test independence (you can't substitute a mock), introduce subtle multi-threading bugs (naive locking slow, double-checked locking famously broken in several languages), and have no defined cleanup order at shutdown. Example: a `Logger.getInstance()` called from every layer means tests can't intercept output, can't run in parallel, and inherit log state from previous tests.
14. **If you genuinely need one instance, hide it behind an interface.** Restrict the global access to a few well-defined construction sites; everywhere else, accept the dependency through a parameter typed by interface. Callers don't know whether a singleton or a fresh object satisfies the interface — and tests can substitute either. *(Saariste, 97/73.)*

### Production resilience (`RI/*`)

When the call will run under load against a downstream that can fail, the per-call hardening *is* the first write. These checks matter most in production code.

15. **Set an explicit timeout on every remote call.** Library defaults are wrong (`None`, "infinity", "many minutes"). Pick a per-call budget based on the downstream's realistic latency plus margin, and cap retries inside that budget. *(`RI/Timeout`.)*
16. **Wrap critical downstreams in a circuit breaker.** Tracked per-downstream failures; once threshold crossed, fail fast locally for a window; probe; close on success. Distinct from retry/backoff: this is "should we attempt at all right now." *(`RI/CircuitBreaker`.)*
17. **Bulkhead resource pools per downstream.** Separate thread pools, connection pools, or queues per external dependency so one stalled downstream cannot exhaust capacity for healthy ones. *(`RI/Bulkhead`.)*
18. **Bounded queues only.** An unbounded queue eventually exhausts memory under load. Pick a cap and an explicit reject policy (drop oldest, drop newest, backpressure to caller). *(`RI/Backpressure`.)*
19. **Fail fast when the request cannot succeed.** Validate at the entry point; check circuit-breaker state and feature flags before expensive setup; return a clear error before holding DB connections, locks, or downstream quota. *(`RI/FailFast`.)*

## Red Flags

These thoughts mean STOP — apply the domain check before committing:

| Thought | Reality |
|---|---|
| "I'll throw the same exception type for both — caller handles either way." | Technical and business exceptions are different contracts. Mixing them means callers can't tell what to guard against beforehand vs. handle after. (97/21) |
| "Empty catch is fine, the error can't happen here." | "Can't happen" is how silent corruption ships. Log, rethrow, or surface the error — never swallow. (97/26) |
| "Nobody on the team knows how this build step works, but it works." | Magic that no one owns is a fault waiting for the day the magic stops. Find the person who knows or document it now. (97/29) |
| "`if (a == b)` for floats is fine, the values are computed the same way." | `0.1 + 0.2 != 0.3`. Use a tolerance scaled to magnitude, or use a decimal type. (97/33) |
| "I'll use `double` for the price column — it's faster than `Decimal`." | Floats accumulate roundoff; money does not forgive roundoff. Use fixed-point or decimal for currency. (97/33) |
| "I'll wrap a lock around the shared map — that fixes the race." | Locks around shared mutable state are where deadlocks and lost updates hide. Prefer message passing; lock only when measured and understood. (97/57) |
| "Failed call → just retry in a loop until it works." | A retry loop without backoff and a cap will hammer the service the moment it recovers. Backoff + jitter + ceiling, and require idempotency on the server. (97/41) |
| "I'll lazy-load each related row — it's cleaner." | One page = thousands of sequential round-trips = visibly broken latency. Count IPCs per stimulus; batch, parallelize, or cache. (97/41) |
| "It's just `for (i = 0; i < strlen(s); ++i)` — looks normal." | `strlen` runs every iteration; an O(n) loop becomes O(n²). Hoist invariants out of hot loops. (97/89) |
| "Linked list is fine, n won't get that big." | "Won't get that big" is how production timeouts are born. Pick the structure by access pattern and confirm with measurement. (97/89, 97/46) |
| "Singleton — there'll only ever be one." | Single-instance is an assumption that ages badly, and the global access point destroys testability. Hide behind an interface, inject the dependency. (97/73) |
| "I'll let the HTTP client default the timeout — it's fine." | Defaults are `None` or hours. Held connections, threads, and queue slots add up under load. Set an explicit per-call timeout. (`RI/Timeout`) |
| "The downstream's flaky — I'll just retry." | Retry without a circuit breaker piles load on a service that's already failing. Wrap critical downstreams in a breaker; fail fast locally when open. (`RI/CircuitBreaker`) |
| "One pool for all downstreams keeps the code simpler." | One slow third party fills the pool and the whole service stops. Bulkhead per downstream; isolate failure domains. (`RI/Bulkhead`) |
| "I'll buffer events in an in-memory queue — it'll catch up." | Unbounded queues exhaust memory under sustained load. Pick a cap and a reject policy; let backpressure inform callers. (`RI/Backpressure`) |
| "I'll validate after the DB lookup — saves a branch." | Late failure holds DB connections, locks, and quota for a request that can't succeed. Validate at the entry; fail fast. (`RI/FailFast`) |

## What "done" looks like

You are done when **all** of the following are true for every domain below your change touches:

- [ ] **Errors:** technical and business exceptions have distinct types; no empty catches; any "magic" the change relies on has a named owner or a documented restart path.
- [ ] **Numerics:** no `==` between floats; tolerances scaled to magnitude; money uses a decimal type; subtractions of near-equal magnitudes have been audited for cancellation.
- [ ] **Concurrency & IPC:** shared mutable state is justified or replaced by message passing; remote calls per user stimulus are counted and bounded; retries have backoff, jitter, and a ceiling.
- [ ] **Limits & Performance:** the data structure matches the access pattern; no invariants recomputed inside hot loops; perf claims are measured, not reasoned.
- [ ] **Globals & Singletons:** any new singleton is justified, narrowly scoped, and accessed through an interface that can be substituted in tests.
- [ ] **Production resilience:** every remote call has an explicit timeout; critical downstreams have a circuit breaker; resource pools are bulkheaded per downstream; queues are bounded with an explicit reject policy; the request fails fast when it cannot succeed.

If any box that applies to your change is unchecked, you are not done. Either finish, or revert and re-plan.

## Principles in this skill

| # | Principle | Author |
|---|---|---|
| 97/21 | Distinguish Business Exceptions from Technical | Dan Bergh Johnsson |
| 97/26 | Don't Ignore That Error! | Pete Goodliffe |
| 97/29 | Don't Rely on "Magic Happens Here" | Alan Griffiths |
| 97/33 | Floating-Point Numbers Aren't Real | Chuck Allison |
| 97/41 | Inter-Process Communication Affects Application Response Time | Randy Stafford |
| 97/46 | Know Your Limits | Greg Colvin |
| 97/57 | Message Passing Leads to Better Scalability in Parallel Systems | Russel Winder |
| 97/73 | Resist the Temptation of the Singleton | Sam Saariste |
| 97/89 | Use the Right Algorithm and Data Structure | Jan Christiaan "JC" van Winkel |
| `RI/Timeout` | Always Set a Timeout | Michael Nygard |
| `RI/CircuitBreaker` | Circuit Breaker | Michael Nygard |
| `RI/Bulkhead` | Bulkhead | Michael Nygard |
| `RI/Backpressure` | Backpressure / Bounded Queues | Michael Nygard |
| `RI/FailFast` | Fail Fast | Michael Nygard |

See `principles.md` for the long-form distillations, citations, and source links.