Remix v2 Error Boundaries Code Review

Targets TypeScript route modules importing from @remix-run/*. No sibling knowledge skill exists for this topic; the canonical mental model is summarized inline below and expanded in references/.

v2 Boundary Model (read first)

Remix v2 unified v1's CatchBoundary + ErrorBoundary into a single ErrorBoundary route-module export. The framework calls it for both thrown Responses (e.g. throw new Response(...), throw json(...)) and thrown runtime errors (loader/action/render exceptions). Inside the boundary you read the value with the useRouteError() hook, then narrow in this order:

1. isRouteErrorResponse(error) → it was a thrown Response; read

error.status, error.statusText, error.data.

1. error instanceof Error → real runtime error; read error.message.
2. else → unknown thrown value; render a generic fallback.

The boundary takes no props. CatchBoundary, useCatch, and the future.v2_errorBoundary flag are all gone — finding any of them is a v1 holdover. Errors render the nearest ErrorBoundary and bubble to the root if none exists; the root boundary remounts the whole document, so it must render <Meta />, <Links />, and <Scripts />. Only thrown loader/action results reach the boundary — a return json(...) with a 4xx status is a successful loader, not an error. Server-side runtime errors also flow through an optional entry.server.tsx handleError export (thrown Responses do not).

Quick Reference

Review Checklist

• [ ] ErrorBoundary declared export function ErrorBoundary() with no props
• [ ] Error read via useRouteError(), not useCatch() and not a prop
• [ ] Narrowing checks isRouteErrorResponse(error) first, then error instanceof Error, then fallback
• [ ] error.data rendered defensively (typed/narrowed before going into JSX)
• [ ] 4xx / 5xx in loaders/actions use throw (not return) for Response / json
• [ ] Routes that can throw export their own ErrorBoundary (don't tear down parents for a widget failure)
• [ ] Root app/root.tsx exports an ErrorBoundary that renders <Meta />, <Links />, and <Scripts />
• [ ] Root boundary uses useRouteLoaderData("root") (not useLoaderData()) when reading root data
• [ ] No CatchBoundary export anywhere; no useCatch import; no future.v2_errorBoundary in remix.config.js
• [ ] entry.server.tsx exports handleError and pipes runtime errors to an error reporter
• [ ] handleError does not assume thrown Responses flow through it (they don't)
• [ ] Thrown values are Response/json/Error instances — never plain strings or POJOs

Valid Patterns (Do NOT Flag)

These are correct Remix v2 usage and must not be reported as issues:

• Route without `ErrorBoundary` that intentionally inherits from a parent — Boundaries cascade up. A child route may omit ErrorBoundary so the parent (or root) renders the fallback. Only flag if the route handles user-distinct error UX and a parent boundary cannot.
• `throw new Response(...)` or `throw json(...)` from a loader/action — The canonical way to signal 404/401/403/etc. This is not "using exceptions for control flow"; it is documented v2 contract.
• Narrowing only with `isRouteErrorResponse(error)` — Acceptable when the route demonstrably only throws Responses and has no render-time crash risk. Severity is ADVISORY at most; suggest adding an instanceof Error branch for defense-in-depth, do not flag as a bug.
• `ErrorBoundary` that does not call `useRouteError()` — Valid when the boundary renders a static "Something went wrong" fallback intentionally (e.g. marketing pages that don't want to surface error detail).
• Root `ErrorBoundary` calling `useRouteLoaderData("root")` and getting `undefined` — Documented defensive pattern (root loader may have thrown). Do not flag the undefined handling as "dead code."
• `handleError` returning early on `request.signal.aborted` — Documented noise filter, not a swallowed error.
• `handleError` not handling thrown `Response`s — By framework contract handleError only fires for runtime errors. The absence of Response handling is correct, not a gap.
• Nested `ErrorBoundary` returning a bare fragment (no `<html>` / `<body>`) — Only the root boundary owns the document. Nested boundaries render inside parent layouts and must not include document tags.

Severity guidance

Use these defaults unless the codebase has documented a different scale:

Hard gates (before writing findings)

Run in order. Do not draft user-facing findings until every gate passes for the batch you are about to report.

1. Location evidence — Pass: Each issue lists the repo path to

the route module (or app/root.tsx, or app/entry.server.tsx) and either a line range or a short verbatim quote from the file you read (not from memory or diff-only guesswork). "The root boundary is wrong" without a path to app/root.tsx is not reportable.

1. Exemption check — Pass: For each issue, you can state in one

line why it is not covered by Valid Patterns (Do NOT Flag). In particular: confirm a missing ErrorBoundary is not a deliberate cascade to a parent boundary; confirm an isRouteErrorResponse-only narrowing is not on a route that demonstrably only throws Responses (downgrade to ADVISORY in that case).

1. v1-vs-v2 marker check — Pass: Before writing the finding,

grep the route module (and the repo at large for cross-cutting issues) for: CatchBoundary, useCatch, v2_errorBoundary, ErrorBoundary({ error, ErrorBoundary({error. If any of these appear, the finding is a v1 holdover (load references/v1-holdovers.md) and must be labeled as such — not as a generic "missing error handling" issue. If none appear, the code is v2-shape and the finding is about v2 correctness.

1. Protocol — Pass: You completed the Pre-Report Verification

Checklist in review-verification-protocol for this review.

Review Questions

1. Does every route that can throw (loader, action, or render) have an

ErrorBoundary at the right level — local where the recovery UI matters, parent/root where cascade is intentional?

1. Does each ErrorBoundary call useRouteError() (not useCatch(),

not props) and narrow isRouteErrorResponse first?

1. Are 4xx / 5xx control flows using throw (not return) so the

boundary actually fires?

1. Does app/root.tsx export an ErrorBoundary with <Meta />,

<Links />, and <Scripts />, and use useRouteLoaderData("root") defensively?

1. Are there any v1 markers left (CatchBoundary, useCatch,

v2_errorBoundary, ({ error }) prop signature)?

1. Is handleError present in entry.server.tsx for runtime-error

observability, with the correct contract (no Response handling)?

Additional Documentation

• Reviewing the ErrorBoundary export shape, hook usage, or narrowing → references/boundary-shape.md
• Reviewing thrown Response / json patterns, handleError, or return-vs-throw → references/throw-response.md
• Reviewing app/root.tsx boundary scaffolding → references/root-boundary.md
• Detecting v1 holdovers (CatchBoundary, useCatch, v2_errorBoundary) → references/v1-holdovers.md
• Remix v2 ErrorBoundary docs: https://remix.run/docs/en/main/route/error-boundary
• Remix v2 error handling guide: https://remix.run/docs/en/main/guides/errors
• Remix v2 entry.server / handleError docs: https://remix.run/docs/en/main/file-conventions/entry.server