Global Error Boundary

A regular error.tsx can only catch errors thrown inside the route segment it belongs to — it cannot catch an error thrown by the root layout.tsx itself, because that layout renders above every error.tsx boundary in the app. For that one special case, Next.js provides a dedicated file: app/global-error.tsx.

Note

global-error.tsx is a true last resort. It only activates when something goes wrong in the root layout or root template — the one piece of UI that wraps literally everything else, including every other error boundary in your app.

It replaces the entire document

Because the root layout normally owns the <html> and <body> tags, and global-error.tsx replaces the root layout when it activates, it must render its own <html> and <body> — there is nothing left above it to provide them.

app/global-error.tsx

TSX

'use client'

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <html>
      <body>
        <h2>Something went seriously wrong!</h2>
        <button type="button" onClick={() => reset()}>
          Try again
        </button>
      </body>
    </html>
  )
}

Warning

Forgetting the <html> and <body> tags in global-error.tsx is a common mistake — since this file stands in for the root layout, skipping them produces a document with no valid HTML skeleton. Like error.tsx, it also must be a Client Component.

error.tsx vs. global-error.tsx

File	Catches errors in	Renders
`error.tsx`	Its own route segment and nested segments	Just the boundary UI — the surrounding layout stays intact
`global-error.tsx`	The root layout / root template only	The full document, including its own `<html>`/`<body>`

In practice, most apps rarely see global-error.tsx trigger — root layouts are usually thin (providers, fonts, a shell) and rarely throw. Still, defining it is good practice: without it, an error in the root layout falls back to Next.js's built-in default error screen, which offers no branding and, in production, no useful detail to the user.

Development vs. production

In development, Next.js shows a detailed overlay with the stack trace regardless of whether you've defined global-error.tsx. In production, that overlay is replaced by whatever your global-error.tsx renders — so it's worth giving users something reassuring rather than a bare "Something went wrong" with no way forward.

global-error.tsx is the only boundary that catches errors thrown in the root layout or root template.
It must be a Client Component and must render its own <html> and <body> tags, since it fully replaces the root layout.
It sits above every other error.tsx boundary — it is the last line of defense, not the first.
Defining it avoids falling back to the generic built-in Next.js error screen in production.