Error Handling

Error Handling Skill

Comprehensive, layered error handling for Next.js applications. This file holds the architecture and contract; copy-paste code is in the references.

• references/patterns.md — error-handling patterns by layer.
• references/examples.md — full worked examples (complete CRUD with errors).
• references/retry-patterns.md — retry, circuit breaker, resilience.
• references/validation-vs-runtime.md — validation vs runtime errors.

Philosophy

1. Never expose internal errors to users — log details server-side, show friendly messages client-side.
2. Use typed errors — ServiceError for any service layer, ActionResponse for server actions.
3. Fail gracefully — error boundaries, fallback UI, retry mechanisms.
4. Log everything — structured logging with context before returning an error.
5. Provide feedback — toast notifications for user-facing errors.

The Four Layers

Client       → Error Boundaries (React) · Toast notifications · inline form-field errors
   ↑
Server Action → ActionResponse<T> / RedirectAction · Zod validation with fieldErrors · toast cookies
   ↑
Service      → ServiceError class · tuple pattern [error, data] · categorizeServiceError()
   ↑
Logging      → structured logs · error context (errorCode, isRetryable, userId), logged before return

The service layer is source-agnostic: the same ServiceError contract wraps failures from a database query, a REST/fetch() API call, or a validation/business-rule check. Nothing below is tied to a particular data store.

Rules per layer (code in references/examples.md):

• Service layer — always return the tuple [error, data]: [ServiceError, null] on failure, [null, data] on success. Wrap external calls in try/catch, run results through categorizeServiceError(error, resourceName), and log before returning.
• Server action — return ActionResponse. Validation failures return fieldErrors (from zod.flatten()) for inline display; service failures set a toast cookie and return a generic user message (never the raw error).
• Client — app/error.tsx error boundary logs the error and offers reset(); toasts surface action feedback; field errors render inline.

ServiceError Contract

ServiceError is the typed error every service-layer operation returns, regardless of where the failure came from — a database driver/ORM, a fetch()/REST call to another service, or a validation/business-rule check. It's a plain TypeScript class with no dependency on any data store. categorizeServiceError(error, resourceName) maps a raw error from any source onto it.

Neutral error-code vocabulary

code is one of these source-independent values. Each concrete adapter (DB driver, HTTP client, validator) maps its own raw error codes/HTTP statuses onto this set:

Factory methods and constructor

ServiceError.notFound("User");            // resource not found
ServiceError.alreadyExists("Budget");     // resource already exists
ServiceError.validation("Invalid input"); // validation / business-rule failed
ServiceError.dataCorruption("Event");     // record exists but data invalid
ServiceError.permissionDenied("Budget");  // auth/permission issue (resource optional)
ServiceError.internal("Budget");          // unknown/unexpected failure

// Full constructor for any other code (e.g. a retryable upstream failure):
//   new ServiceError(code: string, message: string, isRetryable = false)
new ServiceError("external-api", "Payment service unavailable", true);

Error Response Flow

source error (DB / fetch / validation) → categorizeServiceError() → log with context → return [error, null] → server action inspects error flags → set toast cookie → return ActionResponse with a generic message → client shows toast.

Related Skills

• firebase-firestore — one concrete adapter that maps a specific data store's raw errors onto this contract.
• server-actions — ActionResponse types and patterns.
• toast-notifications — user feedback via toasts.
• structured-logging — structured logging patterns; see its references/setup.md for the logger itself and required libraries.