unstable_catchError

The unstable_catchError function creates a component that wraps its children in an error boundary. It provides a programmatic alternative to the error.js file convention, enabling component-level error recovery anywhere in your component tree.

Compared to a custom React error boundary, unstable_catchError is designed to work with Next.js out of the box:

• Built-in error recovery — unstable_retry() re-fetches and re-renders the error boundary's children, including Server Components.
• Framework-aware integration — APIs like redirect() and notFound() work by throwing special errors under the hood. unstable_catchError handles these seamlessly, so they're not accidentally caught by your error boundary.
• Client navigation handling — The error state automatically clears when you do a client navigation to a different route.

unstable_catchError can be called from Client Components.

'use client'
 
import { unstable_catchError, type ErrorInfo } from 'next/error'
 
function ErrorFallback(
  props: { title: string },
  { error, unstable_retry }: ErrorInfo
) {
  return (
    <div>
      <h2>{props.title}</h2>
      <p>{error.message}</p>
      <button onClick={() => unstable_retry()}>Try again</button>
    </div>
  )
}
 
export default unstable_catchError(ErrorFallback)

Reference

Parameters

unstable_catchError accepts a single argument:

const ErrorWrapper = unstable_catchError(fallback)

fallback

A function that renders the error UI when an error is caught. It receives two arguments:

• props — The props passed to the wrapper component (excluding children).
• errorInfo — An object containing information about the error:

The fallback function must be a Client Component (or defined in a 'use client' module).

Returns

unstable_catchError returns a React component that:

• Accepts the same props as your fallback's first argument, plus children.
• Wraps children in an error boundary.
• Renders the fallback when an error is caught in children.

Examples

Client Component

Define a fallback and use the returned component to wrap parts of your UI:

import ErrorWrapper from '../custom-error-boundary'
 
export default function Component({ children }: { children: React.ReactNode }) {
  return <ErrorWrapper title="Dashboard Error">{children}</ErrorWrapper>
}

Recovering from errors

Use unstable_retry() to prompt the user to recover from the error. When called, the function re-fetches and re-renders the error boundary's children. If successful, the fallback is replaced with the re-rendered result.

In most cases, use unstable_retry() instead of reset(). The reset() function only clears the error state and re-renders without re-fetching, which means it won't recover from Server Component errors.

'use client'
 
import { unstable_catchError, type ErrorInfo } from 'next/error'
 
function ErrorFallback(props: {}, { error, unstable_retry, reset }: ErrorInfo) {
  return (
    <div>
      <p>{error.message}</p>
      <button onClick={() => unstable_retry()}>Try again</button>
      <button onClick={() => reset()}>Reset</button>
    </div>
  )
}
 
export default unstable_catchError(ErrorFallback)

Server-rendered error fallback

You can pass server-rendered content as a prop to display data-driven fallback UI. This works by rendering a Server Component as a React.ReactNode prop that the fallback displays when an error is caught.

'use client'
 
import { unstable_catchError, type ErrorInfo } from 'next/error'
 
function ErrorFallback(
  props: { fallback: React.ReactNode },
  errorInfo: ErrorInfo
) {
  return props.fallback
}
 
export default unstable_catchError(ErrorFallback)

Version History