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 , , and . 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 , , and
• [ ] 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 Responses — 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 / ) — 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 ,

, and , 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