Root layout recovery
An exception is thrown while rendering app/layout.tsx.
Next.js 16+ · Directive
global-error
global-error.js is the App Router convention for handling failures in the root layout or template. It is a Client Component that replaces the root layout while active and must render its own html and body elements.
How it works
Place app/global-error.tsx in the root app directory to provide a Client Component fallback for errors in the root layout or template. When active, it replaces that root UI, so it renders its own complete html and body structure and can invoke retry to attempt recovery.
Syntax
export default function GlobalError({ error, retry }: { error: Error & { digest?: string }; retry: () => void }) { /* JSX */ }Parameters
| Name | Type | Description |
|---|---|---|
error | Error & { digest?: string } | The thrown Error; in the documented TypeScript shape it may include an optional digest. |
retry | () => void | Callback used to retry rendering after the error. |
Returns
A React component rendering the global fallback document, including its own html and body elements.
Key points
- Use global-error.js when the failure originates in the root layout or template rather than an ordinary route segment.
- The convention is a file named global-error.js, .jsx, or .tsx directly under app.
- When triggered, the global fallback takes over the document-level UI instead of rendering inside the normal root layout.
- Design the exported component as the user-facing fallback for an unexpected runtime failure.
Common mistakes
- The fallback replaces the root layout or template, so it must supply its own html and body elements.
- Include the use client directive; this boundary cannot be implemented as a Server Component.
- Do not export metadata or generateMetadata from the global error file; use a title element instead if needed.
Example: Global error boundary
'use client'
export default function GlobalError({
error,
retry,
}: {
error: Error & { digest?: string }
retry: () => void
}) {
return (
<html>
<body>
<h2>Something went wrong</h2>
<button onClick={() => retry()}>Try again</button>
</body>
</html>
)
}Save this Client Component as app/global-error.tsx to replace the root layout with a recoverable fallback when a root-level error occurs.
When to use it
Root template fallback
The root template fails before a normal route error boundary can provide the document shell.
Global recovery UI
The application needs a consistent document-level failure screen with a retry action.
Interview questions
QWhat problem does global-error.js solve?
global-error.js is the root-level variation of error.js. It handles errors from the root layout or template and replaces the root layout while active.
Follow-up: Why does the fallback need html and body? Because it replaces the root layout, there is no surrounding document structure to provide those elements.
QWhat props and component requirements does a global error boundary have?
The file must be a Client Component, so it begins with the use client directive. Its component receives an error object and a retry callback, allowing it to display fallback UI and request recovery.
Follow-up: What limitation follows from being a Client Component? Metadata and generateMetadata exports are unsupported, so document title handling should use the title component instead.
QHow would you implement a minimal global error UI?
Create the file in the root app directory as app/global-error.tsx. Render a complete html/body structure and connect a button or similar control to retry for recovery.
Follow-up: Can a nested error.js replace the root layout? No; global-error is the convention intended for errors in the root layout or template.
Related
error.jslayout.jstemplate.jsReact Error BoundarymetadatagenerateMetadatatitle