← All notes
Frontend Development6 min

A Suspense boundary is not an error boundary

App Router dashboards love a single Suspense around a slow widget. That buys a spinner while the Server Component resolves. It does nothing when the fetch throws, the mapper crashes, or a child blows up mid-render. Suspense answers "still waiting." An error boundary answers "this subtree failed." Mixing them into one mental model is how a revenue chart outage takes down the whole page — or how a permanent error keeps showing "Loading…" because nothing ever settled.

Two different questions

Suspense is about unresolved work. An async Server Component, a lazy Client Component, or a streaming slot has not finished yet. The boundary keeps the rest of the tree interactive and swaps in a fallback until the promise resolves. When it resolves successfully, the real UI replaces the fallback.

An error boundary is about a failure that escaped during render. Next.js gives you route-level ones via error.tsx, and component-level ones via catchError. They catch thrown errors in the child tree, render a recovery UI, and — with retry — re-fetch and re-render that segment on the server instead of clearing client state alone.

Those are adjacent controls, not synonyms. A page can be fully loaded and still throw. A page can stream for a long time and never throw. Counting "we wrapped it" as resilience erases which question you answered.

What goes wrong when you treat them as one

Teams wrap a Sanity-backed section in Suspense, ship a skeleton, and assume failures are covered. The query throws. There is no error.tsx near that segment, or the only boundary is global. The whole route collapses into the root fallback while neighboring widgets that were fine disappear with it.

The other failure mode is quieter. A child throws, but the nearest Suspense stays pending forever in the developer's head — they keep tuning the loading UI. Suspense never saw a pending promise to resolve; it saw a crash. You cannot spin your way out of an exception.

loading.tsx is the file convention for the Suspense slot of a segment. error.tsx is the file convention for the error boundary of a segment. Putting one file in the folder does not invent the other. We have seen BuilderHelp-style multi-widget pages and marketing shells both ship with generous loading states and almost no local recovery — then a single broken panel becomes a full-page incident.

Isolate pending and isolate failure

Independent regions need both boundaries when each region can be slow and can fail. Wrap the async work in Suspense so a slow chart does not block the orders list. Put an error boundary around the same region — catchError for a widget, error.tsx for a route segment — so a thrown chart does not unmount the list.

Composition matters. Suspense and error boundaries nest; the order and scope decide what stays up. A single outer Suspense with no inner error boundary still lets one throw climb until it finds a parent that catches. A route-level error.tsx that sits inside the layout keeps chrome; global-error.tsx replaces the document. Choose the blast radius on purpose.

Prefer retry over a client-only reset when the data came from the server. Clearing an error flag without re-fetching re-renders the same broken payload. That is the same class of fake recovery as a catch-block undo on an optimistic overlay — the UI looks decisive and the underlying state never moved.

Expected errors still are not boundary work

Validation failures, empty catalogs, and "this id does not exist" are usually expected paths. Model them as return values, conditional UI, or notFound — not as throws you hope an error boundary will style. Boundaries are for uncaught exceptions, not for the normal no-results branch of a query.

Framework control-flow throws — redirect, notFound, unauthorized — must reach Next.js. A generic third-party ErrorBoundary that swallows digests will paint your fallback instead of the real 404 or redirect. catchError exists partly so those framework errors keep traveling.

Event handlers and plain async callbacks after render still need their own catch-and-setState path. Neither Suspense nor an error boundary is listening there. If the failure happens on click, the boundary you added around the JSX will not save you.

What we check before calling a page resilient

Every independent async region has a loading fallback it owns — Suspense or loading.tsx — and a failure fallback it owns — error.tsx or catchError. No region relies on a spinner to stand in for a crash.

A forced throw in one widget leaves siblings visible. Retry re-fetches server data for that boundary, not just remounts client state. Expected empty and not-found paths do not depend on the error UI.

If those checks fail, the page has pending UX, not failure UX. Treat Suspense as the wait path and the error boundary as the break path, and the dashboard stops pretending a skeleton was a recovery plan.

Questions

Does loading.tsx catch render errors?
No. loading.tsx is the Suspense fallback for the segment while async work is pending. Thrown render errors need error.tsx or a catchError boundary.
Can one wrapper do both jobs?
You can nest them in the same region — Suspense for pending, an error boundary for failure — but one component type does not replace the other. They answer different questions.
When should we use catchError instead of error.tsx?
Use error.tsx for route-segment blast radius. Use catchError when a single widget on a shared page should fail and recover without replacing the whole segment.

Sources

  1. Next.js — Error handling — error.tsx, catchError, retry vs expected errors, global-error.
  2. Next.js — catchError — Component-level boundaries; retry re-fetches server children.
  3. Error Handling in Next.js with catchError — Aurora Scharff — Why generic ErrorBoundary mishandles framework throws and client reset.
  4. Related: A manual undo is not a rollback

Have something to build?

Tell us what you're working on and we'll tell you honestly whether we're the right fit.

Work with us