Error handling

Error handling is an important part of any application. The file-system based router allows you to define custom error components for each layout of your app. When a page fails to render, the error component will be rendered instead. You can also define a fallback component that will be used when an error occurs during the rendering of a page and no error component is defined for the error.

You can define a custom error component by creating a route definition file for any path by using the same rules like normal route files, but named error.jsx. This file will be used to render the error component when an error occurs during the rendering of a page.

// (root).error.jsx

export default function Error({ error }) {
  return <div>{error.message}</div>;
}

You can also define a fallback component by creating a route definition file for any path by using the same rules like normal route files, but named fallback.jsx. This file will be used to render the fallback component when an error occurs during the rendering of a page and no error component is defined for the error.

// (root).fallback.jsx

export default function FallbackError({ error }) {
  return <div>{error.message}</div>;
}

Warning: you can define an error boundary, error fallback or loading component only for layouts, not for pages.

By default, the global error component is the first react-server.error.jsx or react-server.error.tsx file found from the root of your app. This component will be used to render the error component when an error occurs during the rendering of a page and no error component is defined for the error.

Your global error component will be used for all errors that are not handled by a more specific error component. The error component will receive the error as a prop.

// src/app/react-server.error.tsx
export default function GlobalError({ error }: { error: Error }) {
  return <div>{error.message}</div>;
}

Optionally, you can specify the global error component in the react-server.config.json file. You only need to specify the path to the file when you want to use a file that is not named react-server.error.jsx or react-server.error.tsx, like global-error.tsx or similar, or when you want to use a file specifically for the global error component and not the first the framework can find with the default name.

// react-server.config.json
{
  "globalErrorComponent": "src/app/react-server.error.tsx"
}

Your global error component can be a React Server Component or a client component. When it's a client component, it will be rendered on the client side using a React error boundary, while if it's a React Server Component, it will be rendered on the server side only.

Warning: you can't reset a global error boundary! The page needs to be reloaded to reset the error boundary. Use the Refresh component to reload the page using the React Server Component payload. It's recommended to use the noCache prop on the Refresh component to avoid caching issues.