Error handling with error.tsx in NextJS - Deep Dive

Overview - Error handling with error.tsx

What is it?

In Next.js, error handling with error.tsx is a way to catch and display errors that happen during rendering or data fetching in your application. This special file lets you show friendly messages or fallback UI when something goes wrong, instead of crashing the whole app. It works by defining a React component that Next.js uses automatically when errors occur.

Why it matters

Without error handling, users might see broken pages or confusing messages when something fails, which hurts user experience and trust. Error handling with error.tsx helps keep your app stable and user-friendly by gracefully managing unexpected problems. It also helps developers find and fix bugs faster by clearly showing error information.

Where it fits

Before learning error.tsx, you should understand basic React components and Next.js routing. After mastering error handling, you can explore advanced topics like custom error logging, monitoring, and server-side error handling in Next.js.

Mental Model

Core Idea

Error handling with error.tsx is like having a safety net that catches mistakes in your app and shows a helpful message instead of breaking everything.

Think of it like...

Imagine walking on a tightrope with a safety net below. If you slip, the net catches you so you don’t fall hard. Similarly, error.tsx catches app errors so users don’t see a crash.

┌───────────────┐
│ Your Next.js  │
│ Application   │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ error.tsx     │
│ (Error Catch) │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Friendly UI   │
│ or Fallback   │
│ Message       │
└───────────────┘

Build-Up - 6 Steps

1

Foundation

What is error.tsx in Next.js

Concept: Introducing the special error.tsx file and its role in Next.js apps.

In Next.js, error.tsx is a file you place in the app directory to define how your app should respond when an error happens during rendering or data fetching. It exports a React component that Next.js automatically uses to show error messages.

Result

Your app has a dedicated place to show errors instead of crashing or showing blank pages.

Understanding that error.tsx is a built-in Next.js feature helps you handle errors in a consistent and user-friendly way.

2

Foundation

Basic structure of error.tsx component

Concept: How to write a simple error.tsx component that displays an error message.

Create a file named error.tsx in your app folder. Export a React component that receives an error object and shows its message. For example: export default function Error({ error, reset }) { return (

Something went wrong!

{error.message}

) } The reset function lets users retry the failed action.

Result

When an error happens, users see a clear message and a button to retry.

Knowing the error component receives error and reset props lets you build interactive error UIs.

3

Intermediate

Handling different error types gracefully

🤔Before reading on: do you think error.tsx can distinguish between network errors and code errors? Commit to your answer.

Concept: Using error properties to customize the error UI based on error type or status.

Inside error.tsx, you can check error properties like name, message, or status code to show different messages. For example, if error.status === 404, show a 'Page not found' message. If it's a network error, suggest checking the connection. This improves user experience by giving relevant feedback.

Result

Users see tailored error messages that help them understand what went wrong.

Understanding error details lets you create smarter error pages that guide users better.

4

Intermediate

Using the reset function to recover from errors

🤔Before reading on: do you think calling reset() reloads the whole page or just retries the failed part? Commit to your answer.

Concept: The reset function lets you clear the error state and retry rendering without a full page reload.

The reset function passed to error.tsx clears the error boundary and tries to render the component tree again. This is useful for letting users retry after fixing a temporary problem, like a network glitch. Use it in a button's onClick handler to provide a retry option.

Result

Users can recover from errors without refreshing the browser manually.

Knowing reset only retries the failed part keeps your app smooth and responsive.

5

Advanced

Error boundaries vs error.tsx in Next.js

🤔Before reading on: do you think error.tsx replaces React error boundaries or works alongside them? Commit to your answer.

Concept: Understanding how Next.js error.tsx relates to React error boundaries and when to use each.

React error boundaries catch errors in components and let you show fallback UI locally. Next.js error.tsx acts as a global error boundary for the whole app or route segment. You can use both: error.tsx for global errors and React boundaries for smaller parts. This layered approach improves error handling granularity.

Result

Your app handles errors both globally and locally, improving stability and user experience.

Knowing the difference helps you design error handling that fits your app's complexity.

6

Expert

Customizing error.tsx for server and client errors

🤔Before reading on: do you think error.tsx runs on server, client, or both? Commit to your answer.

Concept: How error.tsx works in Next.js's server and client environments and how to tailor it accordingly.

Next.js error.tsx runs on both server and client sides. Server errors happen during data fetching or rendering on the server, while client errors happen in the browser. You can detect the environment using hooks or checks and customize messages or logging. For example, show minimal info on server errors but detailed info on client errors for debugging.

Result

Your error UI adapts to where the error happened, improving security and developer feedback.

Understanding the dual environment nature of error.tsx helps you balance user experience and debugging needs.

Under the Hood

Next.js uses React's error boundaries under the hood to catch errors during rendering or data fetching. When an error occurs, Next.js looks for an error.tsx file in the current route segment or app directory. It then renders the exported component from error.tsx, passing the error object and a reset function. This lets the app show fallback UI without crashing the entire page. The reset function clears the error state and retries rendering the component tree.

Why designed this way?

Next.js designed error.tsx to provide a simple, centralized way to handle errors per route or app segment, improving user experience and developer control. Using React error boundaries internally ensures compatibility with React's rendering model. This approach avoids full page reloads and supports incremental error recovery. Alternatives like global error handlers or manual try-catch blocks were less flexible and harder to maintain.

┌─────────────────────────────┐
│ React Component Tree        │
│ (User UI)                   │
└─────────────┬───────────────┘
              │
       Error occurs here
              │
              ▼
┌─────────────────────────────┐
│ React Error Boundary         │
│ (Catches error)              │
└─────────────┬───────────────┘
              │
              ▼
┌─────────────────────────────┐
│ Next.js error.tsx Component  │
│ (Renders fallback UI)        │
└─────────────┬───────────────┘
              │
       reset() clears error
              │
              ▼
┌─────────────────────────────┐
│ React Component Tree         │
│ (Retries rendering)          │
└─────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does error.tsx catch all JavaScript errors in your Next.js app? Commit to yes or no.

Common Belief: Error.tsx catches every JavaScript error in the app automatically.

Reality: Error.tsx only catches errors during rendering or data fetching in Next.js pages or components. It does not catch errors in event handlers, asynchronous callbacks, or outside React rendering.

Why it matters: Assuming error.tsx catches all errors can lead to missing bugs in event handlers or background tasks, causing unexpected crashes or silent failures.

Quick: Does calling reset() in error.tsx reload the entire browser page? Commit to yes or no.

Common Belief: Calling reset() reloads the whole browser page to fix errors.

Reality: reset() only clears the error state and retries rendering the React component tree without a full page reload.

Why it matters: Thinking reset reloads the page may cause developers to add unnecessary reload logic, harming user experience.

Quick: Can you use error.tsx to handle errors in API routes? Commit to yes or no.

Common Belief: Error.tsx handles errors in API routes automatically.

Reality: Error.tsx only handles errors in the UI rendering layer, not in API routes. API errors must be handled separately with try-catch or middleware.

Why it matters: Confusing UI error handling with API error handling can cause unhandled API errors and poor backend reliability.

Quick: Is error.tsx a replacement for React error boundaries? Commit to yes or no.

Common Belief: Error.tsx replaces the need for React error boundaries in components.

Reality: Error.tsx acts as a global error boundary for Next.js routes but does not replace local React error boundaries, which are useful for catching errors in smaller UI parts.

Why it matters: Ignoring React error boundaries can reduce error handling granularity and make debugging harder.

Expert Zone

1

Error.tsx can be nested in route segments to provide localized error handling, allowing different parts of the app to show custom error UIs.

2

The reset function can be used to reset error state programmatically, enabling complex recovery flows like form resubmission or data refetching.

3

Error.tsx components can integrate with logging services to report errors automatically, balancing user experience with developer monitoring.

When NOT to use

Error.tsx is not suitable for handling errors outside React rendering, such as API route errors, server middleware errors, or global JavaScript errors. For those, use try-catch blocks, middleware error handlers, or global error listeners like window.onerror.

Production Patterns

In production, error.tsx is often customized to show branded error pages with retry buttons and minimal technical details for users. It is combined with logging tools like Sentry to capture error details silently. Developers also use nested error.tsx files to isolate errors to specific app sections, improving user experience and debugging.

Connections

React Error Boundaries

error.tsx builds on React error boundaries by providing a Next.js-specific global error boundary.

Understanding React error boundaries helps grasp how error.tsx catches errors and why it fits naturally in React's rendering model.

API Error Handling

API error handling complements error.tsx by managing backend errors separately from UI errors.

Knowing the separation between UI and API error handling prevents confusion and ensures robust full-stack error management.

Safety Nets in Engineering

error.tsx acts like a safety net in engineering systems that catch failures and prevent total collapse.

Recognizing error.tsx as a safety net clarifies its role in maintaining app stability and user trust.

Common Pitfalls

#1 Showing raw error details to users in production.

Wrong approach:

export default function Error({ error }) {
return Error: {error.message}
}

Correct approach:

export default function Error({ error }) {
return Oops! Something went wrong. Please try again later.
}

Root cause:

Beginners often want to show full error info for debugging but forget this exposes sensitive info and confuses users.

#2 Not using the reset function to allow retrying after errors.

Wrong approach:

export default function Error({ error }) {
return Failed: {error.message}
}

Correct approach:

export default function Error({ error, reset }) {
return <>
Failed: {error.message}

}

Root cause:

Forgetting reset leads to poor user experience because users cannot recover without refreshing the page.

#3 Expecting error.tsx to catch errors in event handlers.

Wrong approach:

throw new Error('Oops') inside a button onClick and expecting error.tsx to catch it.

Correct approach:

Use try-catch inside event handlers or error boundaries wrapping those components.

Root cause:

Misunderstanding that error.tsx only catches rendering and data fetching errors, not event handler errors.

Key Takeaways

Error handling with error.tsx in Next.js provides a centralized way to catch and display errors during rendering or data fetching.

The error.tsx component receives error details and a reset function to show messages and let users retry failed actions smoothly.

It works alongside React error boundaries, offering global error handling per route or app segment.

Error.tsx runs on both server and client, allowing tailored error UIs depending on where the error occurs.

Proper use of error.tsx improves user experience, app stability, and developer debugging without exposing sensitive details.