Overview
About Handling Errors
When building and running your application, you may occasionally encounter build failures, compilation issues, or runtime exceptions. This guide explains how these errors are handled, how to inspect them in your browser or development environment, and how to resolve common problems related to routing, prerendering, and data fetching.
How Errors Are Displayed
During development, the software features an interactive error overlay that catches runtime errors, console errors, and build problems. It provides detailed call stacks, code frames, and links to documentation to help you diagnose and fix issues quickly.
Note
In production builds, sensitive error messages may be omitted or sanitized to prevent leaking confidential details, but stack traces and error digests are recorded for logging and debugging.
Resolving Build and Compilation Issues
Understanding Build Failures
Build errors occur when the application cannot successfully compile due to syntax mistakes, missing dependencies, or strict route matching failures.
Common Build Issues
- Module not found: Occurs when an imported file or package does not exist.
- Missing Sass dependency: If you use built-in Sass support without installing the
sasspackage, the build will fail with a module build error. - Strict route matching failures: Issues such as conflicting parallel route slots or invalid interception routes will trigger build errors or warnings.
Tip
If a production build fails due to a prerender issue, you can rerun the build with the --debug-prerender command-line flag or start development mode using next dev to investigate the error interactively in your browser.
Handling Runtime and Navigation Errors
Understanding Runtime Exceptions
Runtime exceptions happen while your application is running, either on the server or in the browser.
Error Boundaries
The application uses error boundaries to gracefully catch rendering errors in specific parts of your UI without crashing the entire page.
- Explicit Error Boundaries: When an error occurs within a component wrapped by an explicit error boundary, the error is handled by that boundary's custom error UI.
- Implicit (Global) Error Boundaries: If an error is uncaught by any custom boundary, it bubbles up to the global error handler and triggers the development error overlay or global error page.
Warning
Certain internal router errors and navigation bailouts are handled automatically and do not require user intervention.
Static Generation and Prerendering Errors
Understanding Prerender Issues
When configuring routes to be static or optimized for instant navigation, certain dynamic data accesses can cause build blocks or runtime warnings.
Blocking Route and Prerender Errors
Accessing dynamic request data—such as cookies, headers, URL parameters, search parameters, or uncached fetch calls—outside of a <Suspense> boundary can prevent a route from being prerendered.
Ways to fix blocking route issues:
- Wrap the dynamic data access in a
<Suspense fallback={...}>placeholder. - Cache the data access using the
"use cache"directive (does not apply to connection checks). - Set
export const instant = falseto explicitly allow a blocking route.
Troubleshooting Tools
Available Diagnostic Utilities
You can leverage various built-in commands and diagnostic tools to inspect your application's current error state:
- Development Server (
next dev): Automatically surfaces runtime errors and warnings directly in the browser via the interactive overlay. - Production Build Debugging: Use
next build --debug-prerenderto generate detailed stack traces for prerender issues.
Related
On This Page
OverviewAbout Handling ErrorsHow Errors Are DisplayedResolving Build and Compilation IssuesUnderstanding Build FailuresCommon Build IssuesHandling Runtime and Navigation ErrorsUnderstanding Runtime ExceptionsError BoundariesStatic Generation and Prerendering ErrorsUnderstanding Prerender IssuesBlocking Route and Prerender ErrorsTroubleshooting ToolsAvailable Diagnostic UtilitiesRelated