How to Use ErrorBoundary in Remix for Error Handling

In Remix, use the ErrorBoundary export in your route modules to catch runtime errors and show a custom error UI. Define an ErrorBoundary component that receives the error and returns JSX to display a friendly message or recovery options.

Syntax

The ErrorBoundary is a special export in Remix route files. It is a React component that receives an error prop. You return JSX to show when an error happens in that route or its children.

Parts explained:

• export function ErrorBoundary(): Defines the error handler component.
• error prop: The error object caught by Remix.
• Return JSX: The UI shown when an error occurs.

jsx

export function ErrorBoundary({ error }) {
  return (
    <div>
      <h1>Something went wrong</h1>
      <p>{error.message}</p>
    </div>
  );
}

Example

This example shows a Remix route with an ErrorBoundary that catches errors thrown in the loader or component. It displays a friendly message with the error text.

jsx

import { json } from '@remix-run/node';

export async function loader() {
  throw new Error('Failed to load data');
}

export default function ExampleRoute() {
  return <div>This content will not show if loader throws.</div>;
}

export function ErrorBoundary({ error }) {
  return (
    <main style={{ padding: 20 }}>
      <h1>Oops! An error occurred.</h1>
      <p>{error.message}</p>
      <button onClick={() => window.location.reload()}>Try again</button>
    </main>
  );
}

Output

<h1>Oops! An error occurred.</h1>
<p>Failed to load data</p>
<button>Try again</button>

Common Pitfalls

Common mistakes when using ErrorBoundary in Remix include:

• Not exporting ErrorBoundary from the route file, so errors are not caught.
• Throwing errors outside of Remix lifecycle methods (like outside loader/action), which may not be caught.
• Returning invalid JSX or forgetting to use the error prop to show useful info.
• Not providing a way for users to recover or reload after an error.

jsx

/* Wrong: Missing ErrorBoundary export */
export default function Route() {
  throw new Error('Oops');
  return <div>Hello</div>;
}

/* Right: Export ErrorBoundary to catch errors */
export function ErrorBoundary({ error }) {
  return <div>Error: {error.message}</div>;
}

Quick Reference

Tips for using ErrorBoundary in Remix:

• Always export ErrorBoundary from your route modules.
• Use the error prop to show meaningful messages.
• Consider adding a reload button or link for user recovery.
• Errors in loaders, actions, and components are caught by this boundary.
• Use styling and semantic HTML for accessibility.

Key Takeaways

Export an ErrorBoundary component in each Remix route to catch errors.

Use the error prop inside ErrorBoundary to display error details.

Provide user-friendly UI and recovery options like reload buttons.

Errors thrown in loaders, actions, and components are caught by ErrorBoundary.

Not exporting ErrorBoundary means errors will show default Remix error screens.