Errors in nested routes

This page explains how to implement error handling for nested routes in Next.js using error boundaries.

Error propagation in nested routes

When an error occurs in a nested route, it bubbles up through the route hierarchy until it encounters the nearest error boundary. The placement of your error.tsx files determines the scope and granularity of error handling in your application.

Consider a route structure with the following hierarchy:

• Directoryapp/

  • Directoryproducts/

    • error.tsx
    • Directory[productId]/

      • error.tsx
      • Directoryreviews/

        • Directory[reviewId]/

          • error.tsx
          • page.tsx

You can place an error.tsx file at different levels:

• At the products/ level: Handles errors for the entire products section
• At the [productId]/ level: Handles errors for a specific product and its reviews
• At the [reviewId]/ level: Handles errors only for individual reviews

Impact on UI rendering

The location of your error.tsx file affects which parts of your UI are preserved when an error occurs:

• When placed in a parent route (e.g., products/), the error UI replaces the entire route segment and its children
• When placed in a child route (e.g., [reviewId]/), the error UI only replaces that specific segment while maintaining the parent segments’ UI

This granular control allows you to implement precise error handling strategies that maintain as much of your working UI as possible during error states.