Why error boundaries matter in NextJS - Why It Works This Way

Overview - Why error boundaries matter

What is it?

Error boundaries are special components in Next.js that catch JavaScript errors anywhere in their child component tree. They prevent the entire app from crashing by showing a fallback UI instead of breaking the whole page. This helps keep the user experience smooth even when unexpected errors happen.

Why it matters

Without error boundaries, a single error in one part of your app can cause the entire page to stop working, leaving users with a broken screen. This hurts user trust and can cause lost visitors or customers. Error boundaries help isolate problems so the rest of the app stays usable, improving reliability and user satisfaction.

Where it fits

Before learning error boundaries, you should understand React components and basic error handling in JavaScript. After mastering error boundaries, you can explore advanced error reporting, monitoring tools, and server-side error handling in Next.js.

Mental Model

Core Idea

Error boundaries act like safety nets that catch errors in parts of your app so the whole app doesn’t fall apart.

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 all the way down. Error boundaries are like that net for your app’s components.

App Root
  ├─ Error Boundary
  │    ├─ Component A
  │    └─ Component B
  └─ Other Components

If Component A crashes, Error Boundary catches it and shows fallback UI instead of crashing the whole app.

Build-Up - 6 Steps

1

Foundation

What are error boundaries

Concept: Introduce the basic idea of error boundaries as components that catch errors in their children.

In Next.js (built on React), error boundaries are React components that implement special lifecycle methods to catch JavaScript errors during rendering, in lifecycle methods, and in constructors of the whole tree below them. They let you show a fallback UI instead of the broken component tree.

Result

You understand that error boundaries prevent the entire app from crashing by catching errors in parts of the UI.

Understanding that error boundaries isolate errors helps you build more resilient apps that don’t break completely when something goes wrong.

2

Foundation

How to create an error boundary

Concept: Learn the minimal code needed to create an error boundary component in Next.js using React.

Create a class component with static getDerivedStateFromError and componentDidCatch methods. Use state to track if an error happened and render fallback UI accordingly. Example: class ErrorBoundary extends React.Component { constructor(props) { super(props); this.state = { hasError: false }; } static getDerivedStateFromError(error) { return { hasError: true }; } componentDidCatch(error, info) { console.error('Error caught:', error, info); } render() { if (this.state.hasError) { return

Something went wrong.

; } return this.props.children; } }

Result

You can build a component that catches errors in its children and shows a fallback UI.

Knowing the exact methods React uses for error boundaries clarifies how error catching and fallback rendering work.

3

Intermediate

Where to place error boundaries

🤔Before reading on: Do you think placing one error boundary at the app root is enough, or should you use multiple boundaries in different parts? Commit to your answer.

Concept: Learn the strategy of placing error boundaries to isolate errors effectively without overusing them.

You can place one error boundary high in the app tree to catch all errors, but this means any error shows the same fallback UI for the whole app. Alternatively, placing multiple error boundaries around specific components lets you show different fallback UIs and keep unaffected parts working. For example, wrap a user profile section separately from a comments section.

Result

You understand how error boundaries control error isolation and user experience by their placement.

Knowing where to place error boundaries helps balance user experience and debugging ease by isolating errors without hiding too much.

4

Intermediate

Handling errors in server components

🤔Before reading on: Can error boundaries catch errors in Next.js server components? Yes or no? Commit to your answer.

Concept: Understand the limitation that error boundaries only catch errors in client components, not server components.

Next.js uses server components that run on the server and client components that run in the browser. Error boundaries only catch errors in client components because they rely on React lifecycle methods that run in the browser. Errors in server components must be handled differently, often by Next.js error pages or server-side error handling.

Result

You know error boundaries do not catch all errors, especially those from server components.

Understanding this limitation prevents confusion when errors in server components crash the app despite error boundaries.

5

Advanced

Customizing fallback UI and recovery

🤔Before reading on: Do you think fallback UI can include buttons to retry or reset the error state? Commit to your answer.

Concept: Learn how to build interactive fallback UIs that let users recover from errors without reloading the whole page.

Fallback UI can be more than a static message. You can add buttons to retry loading, reset error state, or navigate elsewhere. For example, add a button that calls a method to reset the error boundary’s state, allowing the component to try rendering again. This improves user experience by giving control instead of a dead end.

Result

You can create fallback UIs that help users recover from errors smoothly.

Knowing how to reset error boundaries empowers you to build apps that gracefully recover from transient errors.

6

Expert

Error boundaries and concurrent rendering

🤔Before reading on: Do you think error boundaries behave the same in React’s concurrent mode as in legacy mode? Commit to your answer.

Concept: Explore how React’s concurrent rendering affects error boundaries and their behavior.

React’s concurrent mode changes how rendering happens, allowing interruptions and multiple render attempts. Error boundaries still catch errors, but the timing and frequency of errors can differ. For example, an error might be thrown during a render that is later discarded. React ensures error boundaries handle these cases gracefully, but developers must be aware of potential double renders and side effects.

Result

You understand the subtle differences in error boundary behavior with concurrent rendering.

Knowing these internals helps avoid bugs caused by assumptions about when errors occur and how often fallback UI shows.

Under the Hood

Error boundaries work by implementing React lifecycle methods that catch errors during rendering, lifecycle methods, and constructors of child components. When an error is caught, React stops rendering the faulty subtree and renders the fallback UI instead. The error and info are passed to componentDidCatch for logging or reporting. This prevents the error from bubbling up and crashing the entire app.

Why designed this way?

React was designed to keep apps interactive even when parts fail. Before error boundaries, any error crashed the whole app. The design tradeoff was to isolate errors at component boundaries, allowing partial UI recovery. Alternatives like global try-catch would be too coarse and break React’s declarative model.

App Root
  │
  ├─ Error Boundary
  │    ├─ Child Component (throws error)
  │    └─ Other Child Components
  │
  └─ Other Components

Error thrown → getDerivedStateFromError sets error state → render fallback UI → componentDidCatch logs error

Myth Busters - 4 Common Misconceptions

Quick: Do error boundaries catch errors in event handlers? Commit to yes or no.

Common Belief: Error boundaries catch all errors in React components, including event handlers.

Reality: Error boundaries do NOT catch errors inside event handlers because those errors happen asynchronously. You must handle those errors with try-catch inside the event handler.

Why it matters: Assuming error boundaries catch event handler errors leads to uncaught exceptions and app crashes.

Quick: Can error boundaries catch errors in server-side rendering? Commit to yes or no.

Common Belief: Error boundaries catch errors during server-side rendering in Next.js.

Reality: Error boundaries only work in client-side rendering. Server-side errors must be handled by Next.js error pages or server error handling.

Why it matters: Misunderstanding this causes missed errors on the server and broken user experience.

Quick: Is placing one error boundary at the app root always the best approach? Commit to yes or no.

Common Belief: One global error boundary at the app root is enough to catch all errors.

Reality: Using multiple error boundaries around different parts of the UI provides better error isolation and user experience.

Why it matters: Relying on a single boundary can cause large parts of the UI to disappear on error, frustrating users.

Quick: Do error boundaries catch errors thrown in asynchronous code like promises? Commit to yes or no.

Common Belief: Error boundaries catch errors thrown in asynchronous code like promises.

Reality: Error boundaries do not catch errors in asynchronous code unless those errors are re-thrown during rendering. You must handle async errors separately.

Why it matters: Ignoring this leads to unhandled promise rejections and unexpected app crashes.

Expert Zone

1

Error boundaries do not catch errors in React hooks like useEffect; those must be handled inside the hook or with error reporting.

2

Resetting error boundaries can cause state loss in child components, so design fallback UI carefully to avoid confusing users.

3

In concurrent React, error boundaries may catch errors multiple times due to interrupted renders, requiring idempotent error handling.

When NOT to use

Avoid using error boundaries to hide bugs during development; instead, fix errors early. For global error handling, use monitoring tools like Sentry. For server-side errors, rely on Next.js error pages and API error handling.

Production Patterns

In production, use layered error boundaries: global ones for unexpected errors and local ones for risky UI parts. Combine with error logging services to track and fix issues. Provide user-friendly fallback UI with options to retry or report problems.

Connections

Try-Catch in JavaScript

Error boundaries are like React’s version of try-catch blocks but for UI components.

Understanding try-catch helps grasp how error boundaries catch errors during rendering and lifecycle phases.

Fault Tolerance in Distributed Systems

Error boundaries implement fault isolation similar to how distributed systems isolate failures to prevent cascading crashes.

Knowing fault tolerance principles clarifies why isolating errors in UI components improves overall app reliability.

Safety Nets in Physical Activities

Error boundaries act like safety nets that catch failures to prevent total collapse.

Recognizing this pattern across domains helps appreciate the importance of graceful failure handling.

Common Pitfalls

#1 Assuming error boundaries catch errors in event handlers.

Wrong approach:

function handleClick() {
throw new Error('Oops');
}

// Wrapped in error boundary but error crashes app

Correct approach:

function handleClick() {
try {
throw new Error('Oops');
} catch (e) {
console.error(e);
}
}

Root cause:

Misunderstanding that error boundaries only catch errors during rendering, not in event handlers.

#2 Placing only one error boundary at the app root.

Wrong approach:

// One fallback UI for all errors

Correct approach:

Root cause:

Not realizing multiple boundaries improve error isolation and user experience.

#3 Using error boundaries to hide errors during development.

Wrong approach:

// Ignores fixing the underlying bug

Correct approach:

// Remove error boundary during development to see errors clearly

Root cause:

Misusing error boundaries as a band-aid instead of fixing bugs early.

Key Takeaways

Error boundaries catch rendering errors in React components to prevent the whole app from crashing.

They only catch errors in client components during rendering, not in event handlers or server components.

Placing multiple error boundaries strategically improves user experience by isolating errors to smaller UI parts.

Fallback UI can be interactive, allowing users to retry or recover from errors smoothly.

Understanding error boundaries deeply helps build resilient, user-friendly Next.js applications.