3 · Reliability and delivery · 30 MIN

Loading states and recoverable errors

Loading and error UI belong to the route segment that owns the work.

loading.tsx provides a Suspense fallback while a segment is waiting, and error.tsx defines a client error boundary for recoverable rendering failures beneath it. A retry button calls reset to request another render attempt. Error boundaries do not catch every event-handler or asynchronous callback error, so those operations still need explicit local handling. Keep navigation outside the failing section when possible so the user can leave it. Do not display raw server stack traces, database details or provider tokens in error messages.

Confirm error.tsx is a Client Component.

Read the example

// app/courses/loading.tsx
export default function Loading(){return <p role="status">Loading courses…</p>}
// app/courses/error.tsx (separate file)
'use client';
export default function ErrorView({reset}:{error:Error & {digest?:string};reset:()=>void}) {
  return <section><h2>Courses could not load</h2><p>Your saved progress is unchanged.</p><button onClick={reset}>Try again</button><a href="/">Return home</a></section>;
}

A delayed segment can show Loading courses; a rendering failure shows a retry action and a working home link.

Your challenge

Temporarily delay and fail a child page in a local project, then verify loading, recovery and navigation separately.

Solution cost: Depends on the retried operation; boundary rendering is constant-sized. time · O(1) boundary state plus child rendering. space

Common trap

reset cannot repair an unchanged failing dependency by itself.

// app/courses/loading.tsx
export default function Loading(){return <p role="status">Loading courses…</p>}
// app/courses/error.tsx (separate file)
'use client';
export default function ErrorView({reset}:{error:Error & {digest?:string};reset:()=>void}) {
  return <section><h2>Courses could not load</h2><p>Your saved progress is unchanged.</p><button onClick={reset}>Try again</button><a href="/">Return home</a></section>;
}

Further reading: Official documentation