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.

unstable_catchError can be called from Client Components.

'use client'
 
import { unstable_catchError } from 'next/error'
 
function ErrorFallback(
  props: { title: string },
  { error, unstable_retry: retry }: { error: Error; unstable_retry: () => void }
) {
  return (
    <div>
      <h2>{props.title}</h2>
      <p>{error.message}</p>
      <button onClick={() => 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 retry() to prompt the user to recover from the error. When called, the function re-fetches and re-renders the error boundary's contents. If successful, the fallback is replaced with the re-rendered result.

In most cases, use 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 } from 'next/error'
 
function ErrorFallback(
  props: {},
  {
    error,
    unstable_retry: retry,
    reset,
  }: { error: Error; unstable_retry: () => void; reset: () => void }
) {
  return (
    <div>
      <p>{error.message}</p>
      <button onClick={() => 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.

Good to know: This pattern eagerly renders the fallback on every page render, even when no error occurs. For most use cases, a simpler client-side fallback is sufficient.

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

import ErrorBoundary from '../error-boundary'
 
async function ErrorFallback() {
  const data = await getData()
  return <div>{data.message}</div>
}
 
export default function Component({ children }: { children: React.ReactNode }) {
  return <ErrorBoundary fallback={<ErrorFallback />}>{children}</ErrorBoundary>
}

Good to know:

• Unlike the error.js file convention which is scoped to route segments, unstable_catchError can be used to wrap any part of your component tree for component-level error recovery.
• Props passed to the wrapper component are forwarded to the fallback function, making it easy to create reusable error UIs with different configurations.
• You don't need to wrap error.js default exports with unstable_catchError. The error.js file convention already renders inside a built-in error boundary provided by Next.js.

Version History