existential-birds/beagle / plugins/beagle-react/skills/remix-v2-error-boundaries-review
remix-v2-error-boundaries-review
VerifiedReviews Remix v2 error-handling code for the unified ErrorBoundary, isRouteErrorResponse narrowing, throw-vs-return, root boundary scaffolding, and v1 holdovers (CatchBoundary, useCatch). Use when reviewing routes that throw or define ErrorBoundary in a Remix v2 codebase.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.5 KB |
| references/boundary-shape.md | markdown | 6.1 KB |
| references/root-boundary.md | markdown | 6.4 KB |
| references/throw-response.md | markdown | 7.1 KB |
| references/v1-holdovers.md | markdown | 6.0 KB |
references/boundary-shape.md
View on GitHub# ErrorBoundary Shape — Export, Hook, Narrowing
The v2 `ErrorBoundary` is a route-module export with no props. It reads
the thrown value through `useRouteError()` and must narrow correctly to
distinguish thrown `Response`s from runtime `Error`s. Most boundary
bugs are shape mistakes: props leak in from v1 examples, narrowing
covers one case but not the other, or a route that can throw exports
nothing at all.
## Canonical shape
```tsx
// app/routes/posts.$slug.tsx
import { isRouteErrorResponse, useRouteError } from "@remix-run/react";
export function ErrorBoundary() {
const error = useRouteError();
if (isRouteErrorResponse(error)) {
return (
<section>
<h1>{error.status} {error.statusText}</h1>
<p>{typeof error.data === "string" ? error.data : "Request failed."}</p>
</section>
);
}
if (error instanceof Error) {
return (
<section>
<h1>Something went wrong</h1>
<p>{error.message}</p>
</section>
);
}
return <h1>Unknown error</h1>;
}
```
Three narrowing branches in this order, no props, hook-driven.
## Anti-patterns to flag
### 1. Missing `ErrorBoundary` on a route that can throw
**Pattern**
```tsx
// app/routes/admin.users.$userId.tsx
export async function loader({ params }: LoaderFunctionArgs) {
const user = await db.user.findUnique({ where: { id: params.userId } });
if (!user) throw new Response("Not found", { status: 404 });
return json({ user });
}
export default function UserDetail() {
const { user } = useLoaderData<typeof loader>();
return <UserCard user={user} />;
}
// No ErrorBoundary export.
```
**Why bad**
The thrown 404 bubbles to the nearest ancestor with a boundary —
usually `app/root.tsx`. A whole-document re-render replaces the admin
chrome (nav, sidebar, breadcrumbs) for what should be an inline "user
not found" state. If `app/root.tsx` also lacks a boundary, the user
sees Remix's generic "Application Error" page.
**Fix**
Export a local `ErrorBoundary` that renders inline recovery UI inside
the admin shell:
```tsx
export function ErrorBoundary() {
const error = useRouteError();
if (isRouteErrorResponse(error) && error.status === 404) {
return <p>User not found. <Link to="/admin/users">Back to list</Link></p>;
}
if (error instanceof Error) return <p>Failed to load user: {error.message}</p>;
return <p>Unknown error.</p>;
}
```
**Exemption**: If the route deliberately delegates to a parent boundary
that already renders a good fallback, do *not* flag. Verify the parent
boundary exists and handles this route's error shape before exempting.
### 2. Props on `ErrorBoundary` (v1 carryover)
**Pattern**
```tsx
export function ErrorBoundary({ error }: { error: Error }) {
return <div>{error.message}</div>;
}
```
**Why bad**
In v2 the boundary receives **no props**. `error` is `undefined` at
runtime, so `error.message` throws inside the boundary — causing an
infinite error loop. TypeScript will not catch this because the prop
type is unconstrained.
**Fix**
```tsx
export function ErrorBoundary() {
const error = useRouteError();
// ...narrow...
}
```
### 3. Narrowing only with `instanceof Error`
**Pattern**
```tsx
export function ErrorBoundary() {
const error = useRouteError();
if (error instanceof Error) {
return <p>Error: {error.message}</p>;
}
return <p>Unknown error</p>;
}
```
**Why bad**
Thrown `Response`s are unwrapped to an internal `ErrorResponse`, which
is **not** an `Error` instance. A loader that does `throw json({ message: "Forbidden" }, { status: 403 })`
hits the `"Unknown error"` branch and the 403 status, statusText, and
payload are all lost. The user sees a generic message; the developer
sees no clue what happened.
**Fix**
Check `isRouteErrorResponse(error)` first, then `instanceof Error`:
```tsx
if (isRouteErrorResponse(error)) {
return <p>{error.status}: {String(error.data)}</p>;
}
if (error instanceof Error) {
return <p>Error: {error.message}</p>;
}
return <p>Unknown error</p>;
```
### 4. Narrowing only with `isRouteErrorResponse`
**Pattern**
```tsx
export function ErrorBoundary() {
const error = useRouteError();
if (isRouteErrorResponse(error)) {
return <p>{error.status} {error.statusText}</p>;
}
return <p>Something went wrong</p>;
}
```
**Why bad**
A real bug — null deref, failed DB call, render-time exception —
surfaces as an `Error` instance, not an `ErrorResponse`. With no
`instanceof Error` branch the boundary falls through to the generic
fallback and the developer loses the message and stack at the UI
layer.
**Severity rule**
- **ADVISORY** if the route demonstrably only throws `Response`s
(loader/action use `throw json` / `throw new Response` exclusively
*and* the rendered component is trivial / non-crashing).
- **WARN** otherwise — most routes can render-crash.
**Fix**
Add the `instanceof Error` branch:
```tsx
if (isRouteErrorResponse(error)) return <p>{error.status} {error.statusText}</p>;
if (error instanceof Error) return <p>Error: {error.message}</p>;
return <p>Something went wrong</p>;
```
### 5. Calling `useLoaderData()` inside `ErrorBoundary`
**Pattern**
```tsx
export function ErrorBoundary() {
const data = useLoaderData<typeof loader>();
return <p>Failed for {data.user.name}.</p>;
}
```
**Why bad**
The boundary may be rendering *because the loader threw* — in which
case `useLoaderData()` itself throws, causing a second error and a
boundary loop. Even when the boundary fires from a render-time crash
(not a loader throw), relying on loader data inside the boundary
couples the fallback to a code path that just proved it can fail.
**Fix**
Use `useRouteLoaderData("<route-id>")` and treat the result as possibly
`undefined`, or render a fallback that does not depend on loader data.
## Cross-references
- Throwing patterns (return-vs-throw, `handleError`) → [throw-response.md](throw-response.md)
- Root boundary specifics (`<Meta />`, `<Links />`, `<Scripts />`) → [root-boundary.md](root-boundary.md)
- v1 markers (`CatchBoundary`, `useCatch`) → [v1-holdovers.md](v1-holdovers.md)
- Remix v2 docs: https://remix.run/docs/en/main/route/error-boundary
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |