Global-error.tsx for root errors in NextJS - Step-by-Step Execution

Concept Flow - Global-error.tsx for root errors

Error occurs anywhere

↓

Next.js catches error

↓

Global-error.tsx renders

↓

Show user friendly error UI

↓

User sees error message and options

↓

Optional: Retry or navigate away

When an error happens anywhere in the app, Next.js uses Global-error.tsx to show a friendly error screen to the user.

Execution Sample

NextJS

'use client'

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <main role="alert">
      <h1>Something went wrong</h1>
      <pre>{error.message}</pre>
      <button onClick={() => reset()}>Try again</button>
    </main>
  )
}

This component shows the error message and a button to retry when a root error happens.

Execution Table

Step	Trigger	State Before	Action	State After	What Re-renders	DOM Change
1	Error thrown in app	No error	Next.js detects error	Error object captured	GlobalError component	GlobalError UI mounts with error message
2	GlobalError renders	Error object present	Render error message and retry button	UI shows error details	GlobalError component	DOM shows <h1>, <pre>, <button>
3	User clicks retry	Error shown	Call reset function	Error cleared	App re-renders root	GlobalError unmounts, app reloads
4	No new error	Clean state	Render normal app UI	App UI visible	App components	Normal app DOM shown
5	No error	Normal app running	No action	No change	No re-render	No DOM change

💡 Execution stops when error is cleared and app UI renders normally.

Variable Tracker

Variable	Start	After 1	After 2	After 3	Final
error	undefined	Error object present	Error object present	undefined (reset called)	undefined
UI state	Normal app UI	Error UI shown	Error UI shown	Normal app UI	Normal app UI

Key Moments - 3 Insights

Why does the GlobalError component render instead of the normal app UI?

Because Next.js catches an error and passes it to GlobalError, which replaces the normal UI with the error UI as shown in execution_table step 1 and 2.

What happens when the user clicks the retry button?

The reset function clears the error state, causing the app to re-render normally, removing the error UI as seen in execution_table step 3 and 4.

Is the error UI part of the normal app render cycle?

No, it only renders when an error is caught. Otherwise, the normal app UI renders, shown in execution_table steps 4 and 5.

Visual Quiz - 3 Questions

Look at the execution_table, what is the state of the 'error' variable at step 2?

A Error object present

B undefined

C Error cleared

D Null

💡 Hint

Check the 'State After' column for step 2 in the execution_table.

At which step does the app UI return to normal after an error?

A Step 2

B Step 4

C Step 3

D Step 5

💡 Hint

Look for when 'App UI visible' appears in the 'State After' column.

If the reset function is never called, what happens to the UI?

A App UI reloads automatically

B App crashes

C Error UI stays visible

D UI shows blank screen

💡 Hint

Refer to the variable_tracker showing 'error' stays present without reset.

Concept Snapshot

Global-error.tsx catches root errors in Next.js.
It receives an error and reset function.
Renders a friendly error message and retry button.
Retry calls reset to clear error and reload app UI.
Only shows when an error occurs, otherwise normal UI renders.

Full Transcript

In Next.js 14+, when an error happens anywhere in the app, Next.js catches it and renders the Global-error.tsx component. This component receives the error object and a reset function. It shows a simple UI with the error message and a button to try again. When the user clicks retry, the reset function clears the error state, and the app UI reloads normally. This flow ensures users see a friendly message instead of a broken app. The execution table shows each step: error thrown, GlobalError renders, user retries, and app reloads. The variable tracker follows the error state and UI changes. Key moments clarify why GlobalError replaces the UI and how retry works. The visual quiz tests understanding of error state and UI transitions. This pattern helps handle root errors gracefully in Next.js apps.