Use Error Boundaries

Why this matters

In React, an unhandled error during rendering unmounts the entire component tree. Without error boundaries, a single TypeError: Cannot read property of undefined in one small component crashes the entire page — the user sees a white screen with no indication of what happened and no way to navigate away.

This is catastrophic for user experience. The user cannot:

• See an error message explaining what happened
• Navigate to another page using the app's navigation
• Retry the failed operation
• Report the problem

They must manually refresh the browser, losing any unsaved state. If the error is deterministic (e.g., bad data from the API), refreshing triggers the same crash in an infinite loop.

Error boundaries catch rendering errors in their child component tree, display a fallback UI, and keep the rest of the application functional.

The rule

Wrap distinct UI sections (pages, sidebars, widgets, data-dependent components) in error boundaries. Each boundary should display a contextual fallback UI with a retry action. Never let a single component crash take down the entire application.

Bad example

// No error boundaries — one crash kills everything
export default function DashboardPage() {
  return (
    <div>
      <Header />
      <Sidebar />
      <main>
        <AnalyticsChart />    {/* If this crashes... */}
        <RecentActivity />    {/* ...everything dies */}
        <TeamMembers />
      </main>
    </div>
  );
}

Good example

import { ErrorBoundary } from "react-error-boundary";
 
function ErrorFallback({ error, resetErrorBoundary }: FallbackProps) {
  return (
    <div role="alert" className="p-4 border rounded bg-red-50">
      <h3>Something went wrong</h3>
      <p className="text-sm text-gray-600">{error.message}</p>
      <button onClick={resetErrorBoundary}>Try again</button>
    </div>
  );
}
 
export default function DashboardPage() {
  return (
    <div>
      <Header />
      <Sidebar />
      <main>
        <ErrorBoundary FallbackComponent={ErrorFallback}>
          <AnalyticsChart />    {/* Crash here only affects this section */}
        </ErrorBoundary>
        <ErrorBoundary FallbackComponent={ErrorFallback}>
          <RecentActivity />
        </ErrorBoundary>
        <ErrorBoundary FallbackComponent={ErrorFallback}>
          <TeamMembers />
        </ErrorBoundary>
      </main>
    </div>
  );
}

How to detect

Search for pages that lack error boundaries:

grep -rL 'ErrorBoundary\|error-boundary' app/ --include="*.tsx"

Files in the app/ directory that do not import or use an error boundary are unprotected.

Remediation

1. Install react-error-boundary: npm install react-error-boundary
2. Create a shared ErrorFallback component with retry functionality
3. Wrap each independent UI section in its own ErrorBoundary
4. Add error logging inside the boundary (send to your error tracking service)
5. In Next.js App Router, also add error.tsx files for route-level error handling
6. Test by intentionally throwing in a component to verify the boundary catches it

References

• React: Error Boundaries
• react-error-boundary library
• Next.js: Error Handling