---
title: "Error Handling Debugging"
description: "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, err..."
last_updated: "2026-09-23T10:57:21.246404+00:00"
canonical_url: "https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/guide/troubleshooting/error-handling-debugging"
---

## Overview

### Overview

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.

```mermaid
flowchart TD
    A[Runtime or Hydration Error Occurs] --> B{Environment?}
    B -->|Development| C[Display Interactive Dev Error Overlay]
    B -->|Production| D[Trigger Error Boundary or Fallback]
    C --> E[Inspect Stack Trace, Component Diff, or Code Frame]
    D --> F[Render Graceful Error Fallback or 404/500 Page]
```

## Capturing Runtime Errors

### Overview

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.

### Error Boundaries and Catching Utilities

You can catch errors at different levels of your component tree using built-in error boundaries or granular component-level wrapping.

* **Segment-Level Error Boundaries:** Automatically catch unhandled runtime errors occurring within a specific route segment and render fallback content.
* **Component-Level Error Catching (`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.

### Handling HTTP Status and Not-Found States

Specialized access boundaries handle HTTP status codes such as 404 (Not Found), 403 (Forbidden), and 401 (Unauthorized).

1. Trigger a missing state or redirect when a resource cannot be found or accessed.
2. The HTTP access fallback boundary intercepts the resulting error state.
3. The application renders the designated fallback component (such as a custom 404 page) along with appropriate no-index meta headers.

> [!WARNING]
> Calling `notFound()` directly inside a root layout is not allowed and will trigger a runtime error during development.

## Debugging Rendering and Hydration Issues

### Overview

Hydration discrepancies happen when the HTML rendered on the server does not match what the client initially renders on the browser. 

### Understanding Hydration Discrepancies

When a mismatch occurs, the development overlay inspects the warning type and outputs a comparison helper detailing the mismatch. Common reasons include:
* Using browser-only APIs or dynamic timestamps during initial server rendering.
* Invalid HTML nesting (such as placing a block-level element inside an inline element like a paragraph).
* Extra whitespace or text nodes differing between server and client output.

### Using the Development Overlay

During local development, the built-in error overlay automatically organizes and presents different categories of runtime and build errors. 

| Error Type | Description |
| :--- | :--- |
| `runtime` | Standard JavaScript or React runtime exceptions thrown during execution. |
| `hydration` | Discrepancies between server-rendered HTML and client-side React trees. |
| `blocking-route` | Runtime or uncached data accessed outside of a Suspense boundary during prerendering. |
| `client-hook` | URL or runtime data accessed in a Client Component outside of Suspense. |
| `dynamic-metadata` | Uncached or runtime data accessed inside `generateMetadata()` or `generateViewport()`. |

> [!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.

## Related

- [Routing and Navigation](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/guide/core-concepts/routing-and-navigation)
- [Testing Your Application](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/guide/configuration/testing-your-application)


## Sitemap

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