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

	Operational	Programmer
Examples	bad email, payment declined, upstream 503, rate limit, 404	undefined is not a function, violated invariant, bad migration
Who was wrong	the caller, the network, the world	you
Did you anticipate it	yes — you wrote the throw	no
Correct response	answer the caller, log at warn, keep serving	log at error with stack, let the process die and restart
Process state after	healthy	unknown

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