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.

Practice

1. What is the main purpose of the Global-error.tsx file in a Next.js app?

easy

A. To catch errors anywhere in the app and show a friendly error message

B. To define global CSS styles for the app

C. To handle user authentication and sessions

D. To configure API routes for the backend

Solution

1. Step 1: Understand the role of Global-error.tsx

   This file is designed to catch errors that happen anywhere in the Next.js app, acting as a global error boundary.

2. Step 2: Identify its main function

   It shows a user-friendly error message and allows users to retry or reset the error state.

3. Final Answer:

   To catch errors anywhere in the app and show a friendly error message -> Option A

4. Quick Check:

   Global-error.tsx handles app-wide errors = A [OK]

Hint: Global-error.tsx handles errors globally, not styles or auth [OK]

Common Mistakes:

• Confusing error handling with styling or routing
• Thinking it manages authentication
• Assuming it only catches errors in one component

2. Which of the following is the correct way to define the GlobalError component in Global-error.tsx using React functional components in Next.js?

easy

A. export default function GlobalError({ error, reset }) { return {error.message}; }

B. class GlobalError extends React.Component { render() { return Error; } } export default GlobalError;

C. const GlobalError = () => { return Error; }; export default GlobalError;

D. function GlobalError() { return Error; }

Solution

1. Step 1: Identify React functional component with props

   Next.js uses React functional components with props like { error, reset } for Global-error.tsx.

2. Step 2: Check correct export and props usage

   export default function GlobalError({ error, reset }) { return
   {error.message}; } correctly defines a function with props and exports it as default.

3. Final Answer:

   export default function GlobalError({ error, reset }) { return
   {error.message}
   ; } -> Option A

4. Quick Check:

   Functional component with props and default export = A [OK]

Hint: Use functional component with props and default export [OK]

Common Mistakes:

• Using class components instead of functional
• Missing props in function parameters
• Not exporting the component as default

3. Given this Global-error.tsx snippet, what will be rendered when an error with message "Network failure" occurs?

export default function GlobalError({ error, reset }) {
  return (
    

      
Oops!
      
{error.message}
      Try again
    
  );
}

medium

A. Oops!Network failure

B. Oops!Network failureTry again

C. Oops!Error occurredRetry

D. ErrorNetwork failure

Solution

1. Step 1: Analyze the JSX structure

   The component returns a <main role="alert"> with a heading, paragraph showing error.message, and a button with text "Try again".

2. Step 2: Substitute the error message

   The error message is "Network failure", so the paragraph will show that exact text.

3. Final Answer:

   <main role="alert"><h1>Oops!</h1><p>Network failure</p><button>Try again</button></main> -> Option B

4. Quick Check:

   Rendered output matches JSX with error.message = D [OK]

Hint: Match JSX tags and error.message exactly [OK]

Common Mistakes:

• Ignoring role attribute
• Changing button text
• Using wrong HTML tags or heading levels

4. Identify the error in this Global-error.tsx component code:

export default function GlobalError({ error, reset }) {
  return (
    

      
Error!
      
{error}
      Retry
    
  );
}

medium

A. The reset function is not called correctly

B. The button text should be 'Try again' instead of 'Retry'

C. The component should use <main> instead of <div>

D. The error prop is used directly instead of error.message

Solution

1. Step 1: Check usage of error prop

   The error prop is an object; displaying it directly will show [object Object], not the message.

2. Step 2: Correct way to show error message

   Use error.message to display the actual error text.

3. Final Answer:

   The error prop is used directly instead of error.message -> Option D

4. Quick Check:

   Display error.message, not error object = B [OK]

Hint: Always use error.message to show error text [OK]

Common Mistakes:

• Displaying error object directly
• Ignoring error.message property
• Assuming reset needs parentheses in JSX

5. You want to improve accessibility in your Global-error.tsx component. Which change best helps screen reader users understand the error state?

hard

A. Remove the button to avoid confusion

B. Use <div> instead of semantic tags like <main>

C. Add role="alert" to the main container to announce the error immediately

D. Use only color to indicate the error without text

Solution

1. Step 1: Understand accessibility roles

   The role="alert" attribute tells screen readers to announce the content immediately, which is important for error messages.

2. Step 2: Evaluate other options

   Using semantic tags is good, but role="alert" is more critical for error announcements. Removing buttons or relying on color alone harms accessibility.

3. Final Answer:

   Add role="alert" to the main container to announce the error immediately -> Option C

4. Quick Check:

   Use role="alert" for error announcements = C [OK]

Hint: Use role="alert" to notify screen readers instantly [OK]

Common Mistakes:

• Ignoring ARIA roles for error messages
• Relying on color alone for errors
• Removing interactive elements like retry buttons