Error Handling

Error Handling

Epicenter uses Wellcrafted Results as its internal contract for ordinary failures. This skill owns the full path: define a tagged failure, adapt a throwing dependency, compose or recover from Results, then consume the outcome at the boundary that serves a person or another API. Use logging for diagnostics, query-layer for TanStack observation and cache behavior, and hono for HTTP response mechanics.

Source Of Truth

Ground every Wellcrafted behavior claim in the official wellcrafted-dev/wellcrafted source and tests. When maintaining this guidance, confirm that Epicenter's installed version matches the source being read. If it does not, report the version drift; dependency freshness is handled outside this skill. Treat other skills, examples, generated documentation, and DeepWiki as leads, not authority.

Read the scoped references only when needed:

• Read error variants when designing defineErrors variants, their fields, messages, or union types, or when translating an entire tagged error union.
• Read references/wrapping-boundaries.md when deciding how much work one trySync or tryAsync should cover, especially around cleanup.
• Read references/toast-on-error.md when presenting tagged failures in UI code.
• Read references/http-boundaries.md when mapping failures into Hono responses or deciding which exceptions must keep propagating.

Carry the outcome until a caller settles it

Fallible application work returns Result<T, E> while its caller can recover, add context, or choose how to present the outcome. Compose operations by handling or forwarding each possible Err. Preserve a lower error unless the current operation owns a meaningful new failure. An intentional fallback can return Ok, and a partial success may need success data that records what degraded, so the final caller can respond accurately.

The interaction owner consumes the final outcome into UI state, a toast, an HTTP response, or another host contract. That owner is determined by responsibility and lifetime, not by whether the code lives in an onclick attribute or an operations directory. A terminal action can return void or Promise<void> after settling the outcome. Infallible work stays plain, and unexpected bugs must not become routine Err values.

Do not treat every consumption boundary as an unwrap. Branch on the Result when the caller presents or recovers from an error. Use unwrap when the receiving API already communicates failure by throwing.

Choose The Contract First

Use trySync for a synchronous operation and tryAsync for an operation returning a Promise.

tsCopy code
const { data: response, error } = await tryAsync({
	try: () => fetch(url),
	catch: (cause) => RequestError.TransportFailed({ cause }),
});
if (error !== null) return Err(error);
return Ok(response);

defineErrors factories already return Err(...). Pass the raw cause into the factory and let the factory compose its message with extractErrorMessage. Do not use raw Err(cause) at a catch boundary: thrown values may be null or undefined, and an untyped cause loses the domain failure.

Cross a deliberate throwing boundary

Keep a Result as data while the caller can still recover, report, retry, or propagate. Use unwrap only where the surrounding API already throws as its failure channel:

tsCopy code
import { unwrap } from 'wellcrafted/result';

const document = unwrap(await openDocument(id));

unwrap returns Ok.data and throws Err.error. The throw is the boundary's contract, not a sign the failure was unexpected. Guard on error !== null instead when this function must recover, add context, or clean up.

A conceptual sketch is the one exception: unwrap may stand in for Result branches that do not change the behavior being explained. Say that the sketch throws on failure, and show the branch whenever a failure changes that behavior, such as keeping an unsaved draft after a save conflict.

Consume Every Possible Err Branch

• If a value can be Result<T, E>, inspect or deliberately forward its error branch.
• After destructuring, error is the raw E. Return Err(error), not error.
• If you retained the whole Result, return it unchanged: if (result.error !== null) return result.
• error !== null is the reliable discriminator. Never construct Err(null) or Err(undefined).
• Data-only destructuring is correct when the catch branch always returns Ok<T> and the inferred type collapses to Ok<T>.
• Error-only destructuring is correct when success data is irrelevant. The rule is to handle every possible Err, not to destructure fields you do not use.

Prefer an immediate guard so the success path stays linear.

When a caller translates every variant of a tagged error union, use an exhaustive switch (error.name) with default: error satisfies never. A guard for one variant followed by a shared path is different. See error variants for both shapes.

Own The Promise

tryAsync returns a Promise. Choose its owner explicitly:

• await when this function inspects the Result.
• return tryAsync(...) when the caller owns the Promise<Result<...>>.
• Do not use bare void tryAsync(...): ordinary failures fulfill with Err, so a Promise rejection handler cannot observe them. A best-effort operation still needs an async owner that awaits the Result and explicitly logs or ignores its error branch.
• In UI fire-and-forget code, attach presentation before discarding a Promise that fulfills with a Result: void save().then((result) => toastOnError(result, 'Save failed')). If the Promise can reject, adapt or catch that rejection first.

Keep Native Try-Catch When It Expresses The Contract

Traditional try-catch is appropriate when:

• a finally block owns cleanup;
• a generator must yield a failure rather than return a Result;
• a framework boundary converts an exception directly into its required response shape;
• code catches one known exception and rethrows everything else;
• the surrounding public API intentionally throws.

Do not turn unknown programming errors into a generic domain failure. Mapping every throw to Err can hide bugs behind a misleading retryable error.

Final Check

1. The function's throw-versus-Result contract is explicit.
2. The wrapper covers one coherent failure meaning.
3. Caught values become typed errors, intentional fallbacks, or selective rethrows.
4. Every possible Err branch is handled, forwarded, logged, presented, or explicitly ignored by a named best-effort owner.
5. Unknown bugs still reach the appropriate crash or framework error boundary.