---
title: "Handling Common Errors"
description: "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 inspec..."
last_updated: "2026-10-12T06:40:49.130256+00:00"
canonical_url: "https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/guide/troubleshooting/handling-common-errors"
---

## 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 `sass` package, 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:
1. Wrap the dynamic data access in a `<Suspense fallback={...}>` placeholder.
2. Cache the data access using the `"use cache"` directive (does not apply to connection checks).
3. Set `export const instant = false` to 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-prerender` to generate detailed stack traces for prerender issues.

## Related

- [Server and Client](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/guide/core-features/server-and-client)


## Sitemap

See the full [sitemap](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/llms.txt) for all pages in this wiki.