catchError

Core Idea

catchError cria programaticamente um componente que envolve seus filhos em um error boundary, como alternativa à convenção de arquivo error.js, permitindo recuperação de erro em qualquer ponto da árvore de componentes (não só no nível de route segment).

Key Concepts

• catchError(fallback): importado de next/error; retorna um componente React que envolve children em um error boundary.
• Integração com framework: entende redirect()/notFound() (que lançam erros especiais internamente) e não os captura por engano.
• retry(): re-renderiza os filhos do error boundary dentro de uma Transition, preservando estado de Client Components fora do boundary; recomendado para a maioria dos casos.
• reset(): apenas limpa o estado de erro e re-renderiza sem re-buscar dados; não recupera de erros em Server Component.
• Uso client-only: catchError só pode ser chamado em Client Components ('use client').
• Navegação client: o estado de erro limpa automaticamente ao navegar para outra rota.

Code Examples

'use client'
import { catchError, type ErrorInfo } from 'next/error'

function ErrorFallback(props: { title: string }, { error, retry }: ErrorInfo) {
  return (
    <div>
      <h2>{props.title}</h2>
      <p>{error.message}</p>
      <button onClick={() => retry()}>Try again</button>
    </div>
  )
}

export default catchError(ErrorFallback)

• O que demonstra: criação de um wrapper de error boundary reutilizável, com props customizadas e retry.

import ErrorWrapper from '../custom-error-boundary'

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

• O que demonstra: uso do componente gerado por catchError para envolver parte específica da UI.

Reference Tables

Property (ErrorInfo)	Type	Description
error	Error	instância do erro capturado
retry	() => void	re-busca e re-renderiza os children; substitui fallback se bem-sucedido
reset	() => void	limpa estado de erro e re-renderiza sem re-buscar

Anti-patterns

• Usar reset() em vez de retry() por padrão: reset() não recupera erros vindos de Server Components, só limpa o estado local.
• Envolver error.js com catchError: desnecessário, error.js já renderiza dentro de um boundary embutido do Next.js.

Key Takeaways

1. catchError é a via programática para error boundaries granulares, enquanto error.js é escopado a segmentos de rota.
2. Props passadas ao componente wrapper são repassadas para a função fallback, facilitando UIs de erro reutilizáveis e configuráveis.
3. Um fallback server-rendered pode ser passado como prop ReactNode, mas isso renderiza eagerly em todo render, mesmo sem erro (use com moderação).

Connects To

• error.js: convenção de arquivo equivalente para escopo de route segment; catchError é a via para casos fora desse escopo.
• redirect / notFound: funções cujo comportamento de "throw" é compreendido nativamente por catchError.