Topic

Handle loading and errors

Definition

App Router special files such as loading.tsx and error.tsx define route-segment loading UI and recoverable error boundaries.

In simpler words

Show honest waiting UI and a nearby recovery path when a route cannot render.

Route boundaries complement, rather than replace, request states inside interactive client components.

Open official example (opens in new tab)

After this you can

Add route-level loading and error fallbacks
Explain why error.tsx is client-side
Distinguish route failures from mutation errors

Put fallbacks near the route

loading.tsx supplies immediate feedback while a route segment streams. It should resemble the eventual content enough that the interface does not jump or mislead users.

error.tsx is a Client Component boundary. It receives an error and reset callback so users can retry a transient route-rendering failure without manually refreshing the browser.

A recoverable route error boundary

'use client';
export default function ErrorPage({ reset }: { reset: () => void }) {
  return <section><p role="alert">Could not load this page.</p><button onClick={reset}>Try again</button></section>;
}

The reset callback asks Next to retry the route segment.

Mistake: hiding a failure with null

// Wrong — user sees an unexplained blank screen
if (error) return null;

// Right
if (error) return <p role="alert">Could not load tickets. Try again.</p>;

Every error path needs visible context and a useful next step.

Handle request errors where users act

Definition

A route boundary catches rendering failures, while a Query or mutation error belongs near the list or form that initiated the request.

In simpler words

A failed submit should preserve the user’s draft and explain how to retry.

Use accessible status and alert semantics for asynchronous feedback.

Do not expose raw backend internals in a user-facing message; log diagnostic context separately.

Live playground

Error handling playground

Cause a route and a mutation failure, then compare their recovery UI.

Route segment state

Show skeleton while the segment streams.

Keep in mind

Use loading.tsx for segment-level waiting UI.
Make error.tsx a Client Component that offers reset.
Keep failed form drafts visible for correction and retry.

Test

Check your understanding

At least 10 questions — mix of concept, syntax, practical, and logic. Score ≥80% (enforced by the API) to save progress.

Checking your session…

15 questions · concept 5 · syntax 3 · practical 4 · logic 3

1. error.tsx role?

Concept

Catch missing routes and show a 404 pageCatch errors thrown in the root layout itselfLog errors to the console without rendering anythingCatch errors in the segment and show recovery UI

2. global-error.tsx?

Syntax

A boundary for errors in any nested segmentA handler for all 404 not-found responses app-wideA server-side logger that runs before every requestRoot-level error UI when root layout fails

3. not-found.tsx?

Practical

UI shown when a Server Component throws an errorUI for requests that fail authenticationUI for missing resources/routesUI rendered when a fetch returns a 500 status

4. throw notFound()?

Logic

Trigger the not-found boundary from server codeReturn a 404 Response object from the componentRedirect the user to a /404 routeRender the error.tsx boundary with a 404 message

5. Client error boundaries vs error.tsx?

Concept

error.tsx is a Server Component wrapping a class boundaryRelated ideas — App Router file conventions wire boundaries for youThey are unrelated; error.tsx only handles fetch errorserror.tsx catches build-time errors, not runtime ones

6. Recover action?

Practical

refresh() from error components to refetch server dataretry() passed into the error component as a propreset() from error components to retry renderingreload() from next/navigation to re-run the segment

7. Logging errors?

Syntax

Render the full stack trace so users can report it accuratelyLog on server with enough context; don’t leak stacks to all usersLog only on the client so the server stays lightweightSend the raw error object to the browser console in prod

8. Distinguishing 404 vs 500 in UI?

Logic

Use error.tsx for both and branch on error.statusUse global-error.tsx to separate 404s from 500sCheck response.status in page.tsx and render conditionallyUse not-found vs error boundaries appropriately

9. Async error in Server Component?

Concept

Is swallowed unless you wrap the component in SuspenseBubbles to the client’s window.onerror handlerPropagates to nearest error boundaryReturns a 200 response with an empty body

10. Which practice is best?

Practical

Catch every error and silently render an empty fragmentRedirect to the home page whenever any segment errorsRethrow the error so the whole app unmounts and reloadsProvide useful recovery UI and fix root causes; don’t only console.log

11. What does reset() do here?

Conceptintermediate

'use client';
export default function Error({ error, reset }) {
  return <button onClick={() => reset()}>Retry</button>;
}

Reloads the entire browser tab from scratchRefetches the server data without re-renderingAttempts to re-render the segment that erroredClears the boundary and navigates to the parent route

12. What does calling notFound() do?

Syntaxintermediate

import { notFound } from 'next/navigation';
if (!ticket) notFound();

Renders the nearest error boundary with a 404 codeRenders the nearest not-found boundaryReturns a Response with a 404 status to the browserRedirects to /not-found and updates the URL

13. What is the problem with this error UI in production?

Practicaladvanced

export default function Error({ error }) {
  return <pre>{error.stack}</pre>;
}

error.stack is undefined in production, so it renders blankRendering it forces the segment to reset infinitelyStack traces must be rendered inside global-error.tsx onlyIt leaks stack traces to all users; show a friendly message instead

14. When should each of these render?

Logicadvanced

// app/error.tsx exists, app/not-found.tsx exists

not-found for missing resources; error for thrown runtime errorsnot-found for thrown errors; error for missing resourcesnot-found for 500s; error for 404snot-found on the server; error only on the client

15. Where does this thrown error go?

Conceptintermediate

export default async function Page() {
  const data = await load(); // throws
}

To the nearest not-found.tsx boundaryTo loading.tsx, which shows while the error resolvesTo the nearest error.tsx boundaryTo global-error.tsx, skipping the segment boundary

Checking your session…