errors

Errors and resilience

Error handling is where most Node/Bun services rot, and it rots in a specific way: every catch block makes its own decision. One returns null, one logs and continues, one re-throws a new Error(String(e)) that destroys the stack, one 500s on a validation failure. The result is a service that cannot tell you whether it is healthy, because nothing knows what an error means.

This skill installs one distinction and builds everything on it.

The one distinction: operational vs programmer

The last row is the reason this matters. After a programmer error the process holds state nobody reasoned about — a half-applied transaction, a module that threw during init, a connection pool with a poisoned entry. Continuing is not resilience, it is serving unknown-correctness responses. The famous advice "never swallow errors" is really this: never let a programmer error be swallowed into the operational path.

Everything else in this skill follows mechanically. AppError.isOperational() is the classifier; it returns false for anything that is not an AppError, because an unrecognised error is a bug until proven otherwise.

Copy the module in; never retype it

The subtle parts — the cause chain walk that is cycle-safe, the 5xx message replacement, the re-entrancy guard on shutdown, full-jitter backoff — degrade silently when retyped from memory. 53 tests ship with this code and pass (bun test, tsc --noEmit clean, Bun 1.3.10).

SKILL="${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/skills/errors}"; SKILL="${SKILL:-PASTE_THE_DIR_THIS_SKILL_MD_WAS_READ_FROM}"  # that var is UNSET in a Bash tool (MEASURED) — so paste it. `:?` would ABORT the block and copy nothing
mkdir -p src; if [ -d "$SKILL/assets" ]; then cp -r "$SKILL/assets/errors" src/errors   # app-error, catalog, handler, resilience + 3 test files
else echo "SKILL is still the placeholder — paste the real dir above and re-run"; fi