--- name: backend-error-handling description: > Implement error-handling patterns: boundaries, toasts, one API error shape. Use when "error boundary", "error toast", or "standardize API errors". Plan-only audit → plan-error-handling. Sentry triage → debug-sentry-monitor. license: MIT --- # Error Handling Skill **Degree of freedom: MIXED.** Which layer and message `[HIGH freedom]`; existing-type/boundary probes `[LOW freedom — run exactly]`. ## This skill vs neighbors | Skill | Owns | |---|---| | **backend-error-handling** (this) | Implement error boundaries, toasts, and one API error shape | | `plan-error-handling` | Plan-only audit of silent failures and observability gaps | | `debug-sentry-monitor` | Operate Sentry: triage and fix issues, cut noise, monitor after deploy | ## How to reason 1. **Observe** — existing error types, boundaries, `ActionResult` / `ApiError` 2. **Interpret** — missing layer vs inconsistent shape vs swallowed catch 3. **Classify** — reuse-existing / extend-codes / add-boundary / toast-only 4. **Severity** — unhandled 500 on a mutation outranks a missing toast ## Worked example > **Observe:** `createUser` throws Prisma `P2002`; UI shows a blank catch; `ActionResult` already lives in `types/errors.ts`. > **Interpret:** known conflict is unmapped; no field/toast path. > **Classify:** reuse `ActionResult` + `CONFLICT`; toast the message; do not add a second error type. > **Verify:** duplicate email returns `{ success: false, error: { code: 'CONFLICT' } }`; form alert shown. ## Self-critique before reporting - **Reuse shape** — searched `ActionResult` / `ApiError` / `error.tsx` before adding a type - **User-safe** — `INTERNAL_ERROR` is generic; PII is not in the client message - **Layered** — boundary + action result + toast, not toast-only - **Right owner** — plan-only observability audit → `plan-error-handling`; live Sentry triage → `debug-sentry-monitor` Layered error handling for full-stack apps: one action-result shape, boundaries, and toasts. ## When to Use - Adding error handling to new features - Improving error user experience - Standardizing error responses - Debugging error propagation - Adding error monitoring ## Check existing first [LOW freedom — run exactly] **Before adding ANY error handling, verify:** 1. **Check for existing error types:** ```bash rg "type.*Error|interface.*Error" --type ts rg "ActionResult|ApiError" --type ts ``` 2. **Check for existing error boundaries:** ```bash ls -la app/error.tsx app/global-error.tsx rg "ErrorBoundary" --type tsx ``` 3. **Check for existing error utilities:** ```bash rg "formatError|handleError|reportError" --type ts ls -la src/lib/errors* src/lib/error* 2>/dev/null # @/lib/errors ``` 4. **Check established error response patterns:** ```bash rg "success: false|error:" src/features/*/server/ --type ts | head -10 ``` **Why:** Inconsistent error handling confuses users and complicates debugging. Always follow established patterns. ## Error Handling Layers [HIGH freedom] - **UI layer** — error boundaries, form validation errors, toast notifications. - **Application layer** — Server Action errors, API route errors, business-logic errors. - **Data layer** — database errors, Zod validation errors, external API errors. - Every error is caught at the lowest layer that can name it and surfaces upward as `ActionResult` or a typed API error, never as a raw throw to the UI. Layer diagram: [references/server-patterns.md](references/server-patterns.md) §Error handling layers. ## Standard Error Types [HIGH freedom] - One `AppError { code, message, details? }`; `code` is machine-readable, `message` is user-safe. - `ActionResult` is a discriminated union on `success`; never return `{ data, error }` both-optional. - Error codes: `VALIDATION_ERROR`, `NOT_FOUND`, `UNAUTHORIZED`, `FORBIDDEN`, `CONFLICT`, `RATE_LIMITED`, `INTERNAL_ERROR`. ```typescript // types/errors.ts interface AppError { code: string; message: string; details?: unknown } type ActionResult = | { success: true; data: T } | { success: false; error: AppError } ``` Full `ErrorCode` constant: [references/server-patterns.md](references/server-patterns.md) §Standard error types. ## Server Action Error Handling [HIGH freedom] 1. `safeParse` the `FormData`; return `VALIDATION_ERROR` with `flatten().fieldErrors` as `details`. 2. Check the session; return `UNAUTHORIZED` with a "please sign in" message. 3. Run the mutation, `revalidatePath`, return `{ success: true, data }`. 4. Map known errors (Prisma `P2002` → `CONFLICT` with a specific message). 5. Log unknown errors server-side; return a generic `INTERNAL_ERROR` message, never the stack. ```typescript } catch (error) { if (error instanceof Prisma.PrismaClientKnownRequestError && error.code === 'P2002') { return { success: false, error: { code: 'CONFLICT', message: 'A user with this email already exists' } } } console.error('createUser error:', error) return { success: false, error: { code: 'INTERNAL_ERROR', message: 'Something went wrong. Please try again.' } } } ``` Full `createUser` action: [references/server-patterns.md](references/server-patterns.md) §Server Action error handling. ## Form Error Display (React 19+) [HIGH freedom] - `useActionState(createUser, null)` for state; `useFormStatus` in a child `SubmitButton` for pending. - Field errors come from `state.error.details`; render inline with `aria-invalid` and `aria-describedby`. - Non-validation errors render once in a `role="alert"` banner above the fields. - `useOptimistic` for optimistic UI updates. Full `UserForm` component: [references/ui-patterns.md](references/ui-patterns.md) §Form error display. ## React Error Boundaries [HIGH freedom] - `app/error.tsx` per page segment: `'use client'`, receives `{ error, reset }`, logs in `useEffect`, shows a "Try again" button. - `app/global-error.tsx` for the root: must render its own `` and ``. - Boundaries catch render errors only; async and event errors go through `ActionResult` or TanStack Query. ```tsx // app/error.tsx 'use client' export default function Error({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) { useEffect(() => { console.error('Page error:', error) }, [error]) return (

Something went wrong

) } ``` Both boundaries in full: [references/ui-patterns.md](references/ui-patterns.md) §React error boundaries. ## API Route Error Handling [HIGH freedom] - Same `{ error: { code, message, details? } }` body shape for every non-2xx response. - `400` for `VALIDATION_ERROR` and `INVALID_JSON` (`SyntaxError` from `request.json()`), `201` on create, `500` generic. - Log the route name with the error; never return stack traces. Full `POST /api/products` handler: [references/server-patterns.md](references/server-patterns.md) §API route error handling. ## TanStack Query Error Handling [HIGH freedom] - In `queryFn`/`mutationFn`, throw `new Error(body.error?.message ?? fallback)` when `!res.ok` so the UI gets the server message. - `retry`: no retry on 401/403; up to 3 attempts otherwise. - Mutations: `onSuccess` invalidates the query key and `toast.success`; `onError` → `toast.error(error.message)`. `useProducts` and `useCreateProduct` hooks: [references/ui-patterns.md](references/ui-patterns.md) §TanStack Query error handling. ## Error State UI Components [HIGH freedom] - One reusable `ErrorState({ title, message, onRetry? })`: icon, heading, message, optional retry button. - Use it for query errors (`error` + `refetch`) instead of ad-hoc red text per list. ```tsx const { data, error, isLoading, refetch } = useProducts() if (error) return refetch()} /> ``` Full `ErrorState` component: [references/ui-patterns.md](references/ui-patterns.md) §Error state UI components. ## Further reading - [Error Logging & Monitoring and the full checklist](references/details.md) - [Server-side error patterns](references/server-patterns.md) - [Client-side error patterns](references/ui-patterns.md)