---
title: catchError
description: API Reference for the catchError function.
url: "https://nextjs.org/docs/pages/api-reference/functions/catchError"
docs_index: /docs/pages/llms.txt
lastUpdated: 2026-08-24
prerequisites:
  - "API Reference: /docs/pages/api-reference"
  - "Functions: /docs/pages/api-reference/functions"
---

> For an index of all documentation, see [/docs/pages/llms.txt](/docs/pages/llms.txt).

The `catchError` function creates a component that wraps its children in an error boundary. It provides a programmatic alternative to writing a [custom React error boundary class](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary), enabling component-level error recovery anywhere in your component tree.

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

- **Built-in error recovery** — `reset()` re-renders the error boundary's children, letting users recover from errors without a full page reload.
- **Client navigation handling** — The error state automatically clears when you do a client navigation to a different route.

**TypeScript**

```tsx title="components/custom-error-boundary.tsx" 
import { catchError, type ErrorInfo } from 'next/error'

function ErrorFallback(props: { title: string }, { error, reset }: ErrorInfo) {
  const message = error instanceof Error ? error.message : String(error)

  return (
    <div>
      <h2>{props.title}</h2>
      <p>{message}</p>
      <button onClick={() => reset()}>Try again</button>
    </div>
  )
}

export default catchError(ErrorFallback)
```

**JavaScript**

```jsx title="components/custom-error-boundary.js" 
import { catchError } from 'next/error'

function ErrorFallback(props, { error, reset }) {
  const message = error instanceof Error ? error.message : String(error)

  return (
    <div>
      <h2>{props.title}</h2>
      <p>{message}</p>
      <button onClick={() => reset()}>Try again</button>
    </div>
  )
}

export default catchError(ErrorFallback)
```

## Reference

### Parameters

`catchError` accepts a single argument:

```ts
const ErrorWrapper = 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:

| Property | Type         | Description                                                                                                          |
| -------- | ------------ | -------------------------------------------------------------------------------------------------------------------- |
| `error`  | `unknown`    | The value that was thrown. Narrow it, for example with `instanceof Error`, before reading properties like `message`. |
| `reset`  | `() => void` | Resets the error state and re-renders the error boundary's children.                                                 |

### Returns

`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

### Basic usage

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

**TypeScript**

```tsx title="components/some-component.tsx" 
import ErrorWrapper from './custom-error-boundary'

export default function Component({ children }: { children: React.ReactNode }) {
  return <ErrorWrapper title="Dashboard Error">{children}</ErrorWrapper>
}
```

**JavaScript**

```jsx title="components/some-component.js" 
import ErrorWrapper from './custom-error-boundary'

export default function Component({ children }) {
  return <ErrorWrapper title="Dashboard Error">{children}</ErrorWrapper>
}
```

### Recovering from errors

Use `reset()` to prompt the user to recover from the error. When called, the function clears the error state and re-renders the error boundary's children.

**TypeScript**

```tsx title="components/custom-error-boundary.tsx" 
import { catchError, type ErrorInfo } from 'next/error'

function ErrorFallback(props: {}, { error, reset }: ErrorInfo) {
  const message = error instanceof Error ? error.message : String(error)

  return (
    <div>
      <p>{message}</p>
      <button onClick={() => reset()}>Try again</button>
    </div>
  )
}

export default catchError(ErrorFallback)
```

**JavaScript**

```jsx title="components/custom-error-boundary.js" 
import { catchError } from 'next/error'

function ErrorFallback(props, { error, reset }) {
  const message = error instanceof Error ? error.message : String(error)

  return (
    <div>
      <p>{message}</p>
      <button onClick={() => reset()}>Try again</button>
    </div>
  )
}

export default catchError(ErrorFallback)
```

> **Good to know:**
>
> Props passed to the wrapper component are forwarded to the fallback function, making it easy to create reusable error UIs with different configurations.

## Version History

| Version   | Changes                           |
| --------- | --------------------------------- |
| `v16.3.0` | `catchError` became stable.       |
| `v16.2.0` | `unstable_catchError` introduced. |

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/docs/pages/llms.txt](/docs/pages/llms.txt)