Error.tsx for route errors in NextJS - Deep Dive

Overview - Error.tsx for route errors

What is it?

Error.tsx is a special file in Next.js used to handle errors that happen during routing or rendering of pages. It lets you show a friendly message or UI when something goes wrong instead of a blank or broken page. This file catches errors like failed data loading or unexpected crashes in your app's routes. It helps keep your app user-friendly and stable.

Why it matters

Without Error.tsx, users might see confusing error messages or blank screens when something breaks in your app. This hurts user trust and experience. Error.tsx lets you control what users see during errors, making your app look polished and professional. It also helps developers debug by showing useful info or fallback UI.

Where it fits

Before learning Error.tsx, you should understand basic Next.js routing and React components. After mastering Error.tsx, you can explore advanced error handling like error boundaries, logging, and custom error pages for different HTTP status codes.

Mental Model

Core Idea

Error.tsx acts like a safety net that catches and displays errors happening during page routing or rendering in Next.js apps.

Think of it like...

It's like a safety net under a trapeze artist that catches them if they fall, preventing a hard crash and letting the show go on smoothly.

┌───────────────┐
│ User requests  │
│ a page route  │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Page renders  │
│ (React JSX)   │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Error occurs? │──No──▶ Show page normally
│               │
└──────┬────────┘
       │Yes
       ▼
┌───────────────┐
│ Error.tsx     │
│ renders error │
│ UI fallback   │
└───────────────┘

Build-Up - 7 Steps

1

Foundation

What is Error.tsx in Next.js

Concept: Introduce the special Error.tsx file and its role in Next.js routing.

In Next.js 13 and later, you can create a file named Error.tsx inside your app directory or route folder. This file automatically catches errors that happen during rendering or data fetching for that route. Instead of the app crashing or showing a default error, Next.js shows the UI you define in Error.tsx.

Result

When an error happens in a route, the app shows your custom error UI from Error.tsx instead of a blank or broken page.

Understanding that Error.tsx is a built-in way to catch route errors helps you control user experience during failures.

2

Foundation

Basic structure of Error.tsx component

Concept: Learn how to write a simple Error.tsx component using React and TypeScript.

Error.tsx is a React component that returns JSX. It can be a simple function that returns a message or UI telling the user an error happened. For example: export default function Error() { return

Oops! Something went wrong.

; } This component is rendered automatically when an error occurs in the route.

Result

Your app shows the message 'Oops! Something went wrong.' whenever a route error happens.

Knowing that Error.tsx is just a React component means you can use all React features to customize error UI.

3

Intermediate

Handling errors with reset functionality

🤔Before reading on: do you think Error.tsx can reset the error state to retry rendering, or does it only show static messages? Commit to your answer.

Concept: Learn how to add a reset button in Error.tsx to let users retry loading the route.

Next.js provides a special reset function to clear the error state. You can add a button in Error.tsx that calls reset to try rendering the route again. Example: 'use client'; import { useEffect } from 'react'; export default function Error({ error, reset }: { error: Error; reset: () => void }) { useEffect(() => { console.error(error); }, [error]); return (

Something went wrong!

); } This lets users retry loading the page without a full refresh.

Result

Users see an error message with a button that reloads the route when clicked.

Understanding reset lets you improve user experience by allowing quick recovery from errors.

4

Intermediate

Error.tsx in nested routes and layouts

🤔Before reading on: do you think one Error.tsx file handles all errors in the app, or can you have multiple for different routes? Commit to your answer.

Concept: Explore how Error.tsx files can be placed in nested folders to handle errors locally per route or layout.

Next.js supports nested routing with folders. You can add an Error.tsx file inside any route or layout folder. Errors in that scope show the local Error.tsx UI. For example: /app/dashboard/Error.tsx handles errors only in /dashboard routes. /app/Error.tsx handles errors globally for the whole app. This lets you customize error messages depending on the app section.

Result

Different parts of your app show different error UIs based on where Error.tsx is placed.

Knowing Error.tsx scope helps you design better error handling tailored to app sections.

5

Intermediate

Accessing error details in Error.tsx

Concept: Learn how to receive error information inside Error.tsx to show meaningful messages.

Next.js passes the error object and reset function as props to Error.tsx. You can type them in TypeScript and display error.message or stack trace for debugging: export default function Error({ error, reset }: { error: Error; reset: () => void }) { return (

Error: {error.message}

); } This helps users and developers understand what went wrong.

Result

Error UI shows the actual error message and a retry button.

Accessing error details improves transparency and debugging during failures.

6

Advanced

Integrating Error.tsx with logging and monitoring

🤔Before reading on: do you think Error.tsx should only show UI, or can it also send error info to external services? Commit to your answer.

Concept: Learn how to send error details from Error.tsx to logging or monitoring tools for production tracking.

Inside Error.tsx, you can use useEffect to send error info to services like Sentry or LogRocket: import { useEffect } from 'react'; export default function Error({ error, reset }: { error: Error; reset: () => void }) { useEffect(() => { // Send error to monitoring service console.error('Logging error:', error); // Example: Sentry.captureException(error); }, [error]); return (

Oops! Something went wrong.

); } This helps teams track and fix errors faster.

Result

Errors are logged externally while users see a friendly message and retry option.

Knowing how to integrate error logging from Error.tsx bridges user experience and developer operations.

7

Expert

Surprising behavior of Error.tsx with Suspense and streaming

🤔Before reading on: do you think Error.tsx always catches all errors immediately, or can some errors bypass it in streaming rendering? Commit to your answer.

Concept: Understand how Error.tsx interacts with React Suspense and Next.js streaming rendering, and when errors might not show immediately.

Next.js uses React 18 features like Suspense and streaming for faster page loads. Sometimes, errors inside Suspense boundaries or during streaming may delay or bypass Error.tsx rendering until the stream finishes or fallback triggers. This means Error.tsx might not catch errors instantly or might show after partial content. Developers must test error UI carefully with Suspense and consider adding error boundaries inside components for finer control.

Result

Error.tsx may show errors with delay or partial UI depending on streaming and Suspense behavior.

Understanding this subtlety prevents confusion when error UI behaves unexpectedly in modern React rendering.

Under the Hood

Next.js detects errors thrown during server or client rendering of routes. When an error occurs, Next.js interrupts normal rendering and looks for an Error.tsx file in the current route or layout folder. It then renders this component instead, passing the error object and a reset function. On the client, the reset function clears the error state to retry rendering. This mechanism uses React's error boundaries concept under the hood but integrates it with Next.js routing and streaming rendering.

Why designed this way?

Next.js designed Error.tsx to give developers a simple, file-based way to handle route errors without manual try-catch everywhere. It leverages React's error boundaries but fits them into the new app directory routing system. This design balances ease of use, flexibility, and integration with React 18 features like Suspense and streaming. Alternatives like global error handlers or manual error props were less intuitive and harder to maintain.

┌─────────────────────────────┐
│ Route rendering starts       │
└─────────────┬───────────────┘
              │
              ▼
     ┌─────────────────┐
     │ React renders   │
     │ page components │
     └─────────┬───────┘
               │
       Error thrown?
          ┌────┴─────┐
          │          │
         Yes         No
          │          │
          ▼          ▼
 ┌─────────────────┐  Continue normal
 │ Next.js finds   │  rendering
 │ Error.tsx file  │
 └─────────┬───────┘
           │
           ▼
 ┌─────────────────┐
 │ Render Error.tsx │
 │ with error info  │
 └─────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does Error.tsx catch errors from any component in the app, or only from its route scope? Commit to your answer.

Common Belief: Error.tsx catches all errors globally across the entire Next.js app.

Reality: Error.tsx only catches errors within its route or layout folder scope. Errors outside that scope fall back to higher-level or global Error.tsx files.

Why it matters: Assuming Error.tsx is global can lead to missing error handling in nested routes and unexpected crashes.

Quick: Can you use Error.tsx to handle HTTP status errors like 404 or 500 automatically? Commit to your answer.

Common Belief: Error.tsx automatically handles HTTP errors like 404 Not Found or 500 Internal Server Error.

Reality: Error.tsx handles runtime errors during rendering, but HTTP status errors require separate handling with special files like not-found.tsx or custom server logic.

Why it matters: Confusing these leads to incomplete error handling and poor user experience for missing pages or server errors.

Quick: Does Error.tsx run only on the client side, or also on the server? Commit to your answer.

Common Belief: Error.tsx only runs on the client after the page loads.

Reality: Error.tsx runs both on the server and client during rendering, catching errors in either environment.

Why it matters: Thinking it runs only client-side can cause missed errors during server rendering and inconsistent UI.

Quick: If you throw an error inside a Suspense fallback, will Error.tsx catch it immediately? Commit to your answer.

Common Belief: Error.tsx catches all errors immediately, including those inside Suspense fallbacks.

Reality: Errors inside Suspense fallbacks or during streaming may delay Error.tsx rendering or require additional error boundaries.

Why it matters: Not knowing this causes confusion when error UI appears late or not at all in streaming apps.

Expert Zone

1

Error.tsx can receive a reset function that clears error state, but this reset only works if the error happened during rendering, not during data fetching outside React lifecycle.

2

Placing Error.tsx in layouts vs routes affects error scope and fallback UI hierarchy, which can be used strategically to create layered error handling.

3

Error.tsx integrates with React 18 streaming, so errors may appear after partial content renders, requiring careful UX design to avoid flickering or confusing states.

When NOT to use

Avoid relying solely on Error.tsx for handling API or server errors that happen outside React rendering. Use dedicated error handling in server actions, API routes, or middleware. Also, for global error logging, use centralized services rather than only Error.tsx. For very fine-grained error control inside components, use React error boundaries manually.

Production Patterns

In production, teams place Error.tsx files in key layouts to catch broad errors and add logging inside them to monitor issues. They customize UI per app section for better user guidance. Retry buttons with reset are common to improve recovery. Some use Error.tsx to show fallback skeletons or alternative content. Integration with monitoring tools like Sentry is standard practice.

Connections

React Error Boundaries

Error.tsx builds on React Error Boundaries concept to catch rendering errors.

Understanding React Error Boundaries clarifies how Error.tsx catches errors and why it can reset or fallback UI.

HTTP Status Code Handling

Error.tsx complements but does not replace HTTP error handling like 404 or 500 pages.

Knowing the difference helps design complete error strategies covering both runtime and HTTP errors.

Safety Nets in Engineering

Error.tsx acts as a safety net in software, similar to physical safety nets in construction or sports.

Recognizing error handling as a safety net mindset helps prioritize user experience and system resilience.

Common Pitfalls

#1 Placing Error.tsx only at the root and expecting it to catch all nested route errors.

Wrong approach:

Only /app/Error.tsx exists, but /app/dashboard/Error.tsx is missing, so errors in /dashboard routes crash the app.

Correct approach:

Add /app/dashboard/Error.tsx to handle errors specifically in the dashboard route scope.

Root cause:

Misunderstanding Error.tsx scope and assuming a single global error handler.

#2 Not using the reset function in Error.tsx, leaving users stuck on error screens.

Wrong approach:

export default function Error() { return Error occurred; }

Correct approach:

export default function Error({ reset }: { reset: () => void }) { return ; }

Root cause:

Ignoring Next.js reset mechanism that allows retrying route rendering.

#3 Trying to handle 404 or 500 errors inside Error.tsx instead of using dedicated files.

Wrong approach:

Using Error.tsx to show 'Page not found' for missing routes.

Correct approach:

Create not-found.tsx or error.tsx files specifically for HTTP status handling.

Root cause:

Confusing runtime rendering errors with HTTP status errors.

Key Takeaways

Error.tsx is a special React component in Next.js that catches and displays errors during route rendering.

You can place Error.tsx files in nested routes or layouts to scope error handling locally.

Error.tsx receives the error object and a reset function to show details and allow retrying.

It runs on both server and client, integrating with React 18 features like Suspense and streaming.

Proper use of Error.tsx improves user experience, debugging, and production error monitoring.