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.

Practice

1. What is the main purpose of the error.tsx file in a Next.js route?

easy

A. To catch and display errors that happen in that route

B. To define the page layout and styles

C. To fetch data from an API

D. To handle user authentication

Solution

1. Step 1: Understand the role of error.tsx

   This file is designed to catch errors that occur in its route and show a friendly message to users.

2. Step 2: Compare with other options

   Options A, C, and D describe unrelated tasks like layout, data fetching, or authentication, which are not the purpose of error.tsx.

3. Final Answer:

   To catch and display errors that happen in that route -> Option A

4. Quick Check:

   Error handling = To catch and display errors that happen in that route [OK]

Hint: Remember: error.tsx shows errors in its route [OK]

Common Mistakes:

• Confusing error.tsx with layout.tsx
• Thinking error.tsx fetches data
• Assuming error.tsx manages authentication

2. Which of the following is the correct way to export an error component in error.tsx for Next.js?

easy

A. const Error = () => { Error occurred }; export default Error;

B. function Error() { return Error occurred; }

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

D. export function Error() { return Error occurred; }

Solution

1. Step 1: Check correct export syntax

   Next.js expects a default export for the error component in error.tsx. export default function Error() { return

   Error occurred

   ; } uses export default function, which is correct.

2. Step 2: Identify syntax errors in other options

   function Error() { return

   Error occurred

   ; } lacks export, so it won't be recognized. export function Error() { return

   Error occurred

   ; } exports a named function, not default. const Error = () => {

   Error occurred

   }; export default Error; misses a return statement inside the arrow function, causing no output.

3. Final Answer:

   export default function Error() { return <p>Error occurred</p>; } -> Option C

4. Quick Check:

   Default export function = export default function Error() { return

   Error occurred

   ; } [OK]

Hint: Use default export function for error component [OK]

Common Mistakes:

• Forgetting to export default
• Using named exports instead of default
• Missing return statement in arrow function

3. Given this error.tsx component, what will be rendered when an error occurs?

export default function Error() {
  return (
    <section role="alert">
      <h1>Oops! Something went wrong.</h1>
      <button onClick={() => window.location.reload()}>Try again</button>
    </section>
  );
}

medium

A. An error message but no button

B. A blank page with no content

C. A console error but no UI change

D. A section with a heading and a button that reloads the page

Solution

1. Step 1: Analyze the JSX structure

   The component returns a <section> with role="alert", containing a heading and a button with an onClick that reloads the page.

2. Step 2: Understand the rendered output

   When an error happens, this UI shows a message and a clickable button that refreshes the page, matching A section with a heading and a button that reloads the page.

3. Final Answer:

   A section with a heading and a button that reloads the page -> Option D

4. Quick Check:

   JSX returns alert section with reload button = A section with a heading and a button that reloads the page [OK]

Hint: Look for JSX elements and event handlers to predict output [OK]

Common Mistakes:

• Ignoring the button's onClick behavior
• Assuming no UI renders on error
• Confusing role attribute with content

4. You wrote this error.tsx but it does not show the error UI when an error happens:

function Error() {
  return <p>Error!</p>;
}
export default Error;

What is the likely problem?

medium

A. The component name must be lowercase

B. The file must be named error.tsx and placed in the route folder

C. The component is not exported as default

D. The component must return a div, not a p

Solution

1. Step 1: Check export and component name

   The component is exported as default and named with uppercase, which is correct.

2. Step 2: Verify file placement and naming

   Next.js requires the error.tsx file to be in the route folder to catch errors there. If misplaced or misnamed, it won't work.

3. Final Answer:

   The file must be named <code>error.tsx</code> and placed in the route folder -> Option B

4. Quick Check:

   Correct file name and location = The file must be named error.tsx and placed in the route folder [OK]

Hint: Check file name and folder location for error.tsx [OK]

Common Mistakes:

• Using lowercase component name
• Returning wrong HTML tags
• Not placing error.tsx in the route folder

5. You want to improve accessibility in your error.tsx component. Which change best helps screen reader users?

hard

A. Add role="alert" to the container element

B. Use only <div> elements without roles

C. Remove all buttons to avoid confusion

D. Use inline styles to highlight the error text

Solution

1. Step 1: Understand accessibility roles

   Adding role="alert" tells screen readers to announce the error immediately, improving accessibility.

2. Step 2: Evaluate other options

   Use only <div> elements without roles lacks roles, reducing accessibility. Remove all buttons to avoid confusion removes helpful retry buttons. Use inline styles to highlight the error text styles visually but doesn't help screen readers.

3. Final Answer:

   Add <code>role="alert"</code> to the container element -> Option A

4. Quick Check:

   Use ARIA roles for accessibility = Add role="alert" to the container element [OK]

Hint: Use ARIA roles like role="alert" for error messages [OK]

Common Mistakes:

• Ignoring ARIA roles for screen readers
• Removing interactive elements unnecessarily
• Relying only on visual styles for errors