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/throw-response.md
View on GitHub# Throw vs Return — Responses, Errors, and `handleError`
In Remix v2, only **thrown** values reach `ErrorBoundary`. A `return`
from a loader/action is a successful result — no matter the status
code. Choosing throw-vs-return wrong is one of the most common
boundary bugs because the code looks correct and types check.
Companion: `app/entry.server.tsx` may export `handleError` for
server-side error reporting. Its contract has a sharp edge: it does
**not** fire for thrown `Response`s.
## Canonical patterns
```tsx
// Loader: throw for 4xx/5xx, return for success
export async function loader({ params }: LoaderFunctionArgs) {
invariant(params.invoiceId, "Missing invoiceId");
const invoice = await db.invoice.findUnique({ where: { id: params.invoiceId } });
if (!invoice) {
throw json({ message: `Invoice ${params.invoiceId} not found` }, { status: 404 });
}
return json({ invoice });
}
// Action: throw for auth / validation hard-stops, return for field errors
export async function action({ request }: ActionFunctionArgs) {
const user = await requireUser(request); // throws Response on 401
const form = await request.formData();
const parsed = schema.safeParse(Object.fromEntries(form));
if (!parsed.success) {
return json({ errors: parsed.error.flatten() }, { status: 400 }); // returned — rendered by route
}
await db.invoice.update({ where: { id: parsed.data.id }, data: parsed.data });
return redirect(`/invoices/${parsed.data.id}`);
}
```
```tsx
// app/entry.server.tsx
export function handleError(
error: unknown,
{ request }: LoaderFunctionArgs | ActionFunctionArgs,
) {
if (request.signal.aborted) return; // ignore client disconnects
if (error instanceof Error) {
reportToSentry(error);
} else {
console.error("Non-Error thrown server-side:", error);
}
}
```
## Anti-patterns to flag
### 1. Returning instead of throwing for 4xx / 5xx
**Pattern**
```tsx
export async function loader({ params }: LoaderFunctionArgs) {
const post = await db.post.findUnique({ where: { slug: params.slug } });
if (!post) {
return json({ error: "Not found" }, { status: 404 }); // returned, not thrown
}
return json({ post });
}
export default function Post() {
const data = useLoaderData<typeof loader>();
if ("error" in data) return <p>{data.error}</p>; // ad-hoc error branch
return <article>{data.post.title}</article>;
}
```
**Why bad**
- The 404 case does *not* reach `ErrorBoundary`. The component now
carries two-shape `data` and must branch on `"error" in data` —
defeating the v2 model.
- The browser sees a 404 status with a successful HTML body. SEO tools
and crawlers get mixed signals.
- The component types become a discriminated union of "success" and
"error" shapes, which leaks into every consumer.
**Fix**
```tsx
if (!post) throw json({ message: "Not found" }, { status: 404 });
return json({ post });
```
The boundary now renders the 404; the component only deals with the
success shape.
### 2. Swallowing `error.data` (rendering an object as text)
**Pattern**
```tsx
export function ErrorBoundary() {
const error = useRouteError();
if (isRouteErrorResponse(error)) {
return <p>{error.data}</p>; // error.data may be object
}
return null;
}
```
If the loader did `throw json({ message: "Forbidden" }, { status: 403 })`,
then `error.data` is `{ message: "Forbidden" }`. React renders this as
`"Objects are not valid as a React child"` and the boundary itself
crashes.
**Why bad**
`error.data` is typed `unknown`. The shape depends entirely on what
the loader threw. Boundaries that assume "data is a string" work for
some routes and fail for others.
**Fix**
Type-narrow before rendering:
```tsx
if (isRouteErrorResponse(error)) {
const msg =
typeof error.data === "string"
? error.data
: typeof error.data === "object" && error.data && "message" in error.data
? String((error.data as { message: unknown }).message)
: error.statusText;
return <p>{msg}</p>;
}
```
Or define a shared `ErrorPayload` type and `throw json<ErrorPayload>(...)`.
### 3. Throwing a non-`Response` / non-`Error` value
**Pattern**
```tsx
if (!input.email) throw "Email required"; // string
if (!user) throw { code: 401, message: "Unauthorized" }; // POJO
```
**Why bad**
`useRouteError()` returns the value as `unknown`. Neither
`isRouteErrorResponse(error)` nor `error instanceof Error` matches, so
the boundary falls through to the "Unknown error" branch. Status code
information is lost. `handleError` receives a non-`Error` value and
typically logs `"Non-Error thrown server-side"` with no stack.
**Fix**
Always throw a `Response` (for expected control flow — 4xx) or an
`Error` (for bugs — 5xx):
```tsx
if (!input.email) throw new Response("Email required", { status: 400 });
if (!user) throw json({ message: "Unauthorized" }, { status: 401 });
if (db.connection.state === "broken") throw new Error("DB connection lost");
```
### 4. Missing `handleError` in `entry.server.tsx`
**Pattern**
`app/entry.server.tsx` exports only `handleRequest`. No `handleError`,
no other server logging in place.
**Why bad**
In production, Remix logs runtime errors to `console.error` and shows
"Application Error" to the user. Without `handleError` the errors are
never piped to Sentry / Datadog / your reporter — they vanish into
stdout (or stderr depending on the host). You only learn about bugs
when users report them.
**Fix**
Export `handleError`. Filter aborted requests, narrow by type, report:
```tsx
export function handleError(error: unknown, { request }: LoaderFunctionArgs | ActionFunctionArgs) {
if (request.signal.aborted) return;
if (error instanceof Error) Sentry.captureException(error);
else console.error("Non-Error thrown:", error);
}
```
### 5. Logging thrown `Response`s through `handleError`
**Pattern**
```tsx
export function handleError(error: unknown, { request }: LoaderFunctionArgs | ActionFunctionArgs) {
Sentry.captureException(error); // also for Responses?
}
```
Then someone wraps a loader in `try { ... } catch (e) { handleError(e, ...); throw e; }`
to "make sure 404s are tracked."
**Why bad**
`handleError` is **never** called for thrown `Response`s by the
framework — Remix treats them as expected control flow. Manually
re-routing every 404/403 through Sentry turns normal user navigation
("user clicks expired link") into pages of error alerts and burns the
Sentry quota.
**Fix**
Trust the framework contract. If you need to track specific 4xx for
product reasons (e.g., suspicious 403 spikes), log at the **throw
site** with structured fields — not through `handleError`:
```tsx
if (!user) {
metrics.increment("auth.unauthorized", { route: "/admin" });
throw json({ message: "Unauthorized" }, { status: 401 });
}
```
## Cross-references
- Boundary shape (narrowing, props, hook) → [boundary-shape.md](boundary-shape.md)
- Root boundary specifics → [root-boundary.md](root-boundary.md)
- `handleError` doc: https://remix.run/docs/en/main/file-conventions/entry.server
- `throw` semantics: https://remix.run/docs/en/main/guides/errors
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 |