Getting Started
Core Concepts
Troubleshooting
The error handling and debugging system helps you capture runtime exceptions, manage not-found or access-restricted states, and resolve rendering or hydration discrepancies. During development, errors are surfaced through an interactive overlay that provides helpful stack traces, code frames, and specific guidance for fixing issues like missing Suspense boundaries or mismatched server and client HTML. In production, built-in error boundaries, fallback pages, and error-catching utilities ensure your application degrades gracefully instead of crashing entirely.
Next.js provides several mechanisms to catch and handle runtime errors gracefully on both the server and client sides, preventing white screens of death and giving users options to recover.
You can catch errors at different levels of your component tree using built-in error boundaries or granular component-level wrapping.
catchError): Wrap individual client components to manage localized failures without disrupting the entire page layout. The fallback component receives error information alongside a reset function.Note
The retry() function provided to error boundaries can only be used in the App Router to refresh the router state. Use reset() instead when working in the Pages Router.
Specialized access boundaries handle HTTP status codes such as 404 (Not Found), 403 (Forbidden), and 401 (Unauthorized).
Warning
Calling notFound() directly inside a root layout is not allowed and will trigger a runtime error during development.
Hydration discrepancies happen when the HTML rendered on the server does not match what the client initially renders on the browser.
When a mismatch occurs, the development overlay inspects the warning type and outputs a comparison helper detailing the mismatch. Common reasons include:
During local development, the built-in error overlay automatically organizes and presents different categories of runtime and build errors.
Tip
When investigating production build prerendering issues, you can rerun your production build with the flag next build --debug-prerender to generate detailed stack traces and locate the source of unhandled data access.