The global-error.js Convention

The absolute last line of defense for root layout crashes.

Next.js4 min readConcept 11 of 65

The root crash problem

We know that an error.js file catches errors in its segment, but because it is nested *inside* the layout of the same folder, it cannot catch errors thrown by that layout.

So, what happens if your absolute Root Layout (app/layout.tsx) crashes? A standard app/error.tsx cannot catch it. Without intervention, your entire application goes down.

This is exactly what global-error.js is designed to solve.

Total replacement

global-error.js sits at the absolute top of the component tree, wrapping even the Root Layout.

When a catastrophic error occurs in the Root Layout (e.g., your global theme provider throws an error, or the root data fetch fails), global-error.js completely replaces the Root Layout to show a fallback UI.

Mandatory HTML tags

Because global-error.js physically replaces the Root Layout, it is responsible for rendering the foundational HTML document.

Therefore, a global-error.js component **must** define its own <html> and <body> tags. Like all error boundaries, it must also include the 'use client' directive.

The Component Hierarchy

Study the nesting diagram below. Notice how the standard ErrorBoundary sits inside the RootLayout, making it impossible to catch a root crash. Only the GlobalError sits outside everything.

global-error.tsx

Absolute top-level boundary

Replaces HTML & BODY tags

Root layout.tsx
Fatal Error Thrown
error.tsx (Standard)

Bypassed: The crash happened ABOVE this boundary.

page.tsx

Because Next.js nests the standard error.tsx inside the layout of the same folder, it cannot catch an error thrown by the Root Layout itself. To prevent the entire app from failing, you must use a global-error.tsx file, which wraps outside everything and replaces the HTML document.

Check yourself

Pick an answer to lock it in, then read why. Getting one wrong is part of how it sticks.

  1. 1Unlike a standard error.js, what MUST a global-error.js component return?
  2. 2Why can't you just put a standard error.js in the app/ folder to catch Root Layout errors?

Remember this

  • global-error.js catches errors in the Root Layout.
  • It completely replaces the Root Layout when active.
  • It MUST define its own <html> and <body> tags.
  • It is hard to test in dev mode (Next.js shows an overlay instead).

Done with this concept?

Mark it complete to track your progress. No login needed.