How to define and use defineErrors from wellcrafted. Use when creating new error types, updating error definitions, or reviewing error patterns. Covers variant factories, extractErrorMessage for cause, InferErrors/InferError for types, and call site patterns.
Related Skills: See
error-handlingfor trySync/tryAsync usage and toast-on-error patterns. Seeservices-layerfor service architecture and namespace exports.
Use this pattern when you need to:
defineErrors.cause: unknown.extractErrorMessage(cause) inside variant factories.InferErrors/InferError.createTaggedError and split Err-pair patterns.import {
defineErrors,
extractErrorMessage,
type InferErrors,
type InferError,
} from 'wellcrafted/error';
defineErrors call — never spread them across multiple calls{ message, ...fields } — that is the entire API; no .withMessage(), .withContext(), or .withCause() chainscause: unknown is just a field like any other — accept it in the input and forward it in the return objectextractErrorMessage(cause) inside the factory, never at the call siteMyError.Variant({ ... }) returns Err(...) automatically — no separate FooErr pairInferErrors — const FooError / type FooErrorInferError<typeof FooError.Variant> to extract a single variant's type when neededService, Error, or Failed.message for end-user readability — toastOnError shows .message as the muted toast description below the bold title. Write messages that make sense to users, not just developers. Avoid raw paths, status codes, or stack traces as the primary message. Include them after a human-readable prefix:// ✅ GOOD — human-readable prefix, technical detail after