Error Handling

Core Idea

Como tratar erros em três camadas no Pages Router: overlay de desenvolvimento, erros de servidor (página 500) e erros de cliente (React Error Boundaries).

Key Concepts

• Dev overlay: modal automático mostrado só com next dev; some quando o erro é corrigido; não aparece em produção.
• 500 page: pages/500.js customiza a página estática padrão para erros de servidor; não expõe o erro real ao usuário.
• 404 page: trata erros específicos de runtime como "file not found" (ver custom-error docs).
• ErrorBoundary: componente de classe React usando getDerivedStateFromError e componentDidCatch, envolvendo Component em pages/_app.js.

Code Examples

class ErrorBoundary extends React.Component {
  constructor(props) {
    super(props)
    this.state = { hasError: false }
  }
  static getDerivedStateFromError(error) {
    return { hasError: true }
  }
  componentDidCatch(error, errorInfo) {
    console.log({ error, errorInfo })
  }
  render() {
    if (this.state.hasError) {
      return (
        <div>
          <h2>Oops, there is an error!</h2>
          <button type="button" onClick={() => this.setState({ hasError: false })}>
            Try again?
          </button>
        </div>
      )
    }
    return this.props.children
  }
}

export default ErrorBoundary

• O que demonstra: Error Boundary padrão (React) com estado hasError, fallback UI e reset manual.

// pages/_app.js
import ErrorBoundary from '../components/ErrorBoundary'

function MyApp({ Component, pageProps }) {
  return (
    <ErrorBoundary>
      <Component {...pageProps} />
    </ErrorBoundary>
  )
}

export default MyApp

• O que demonstra: wrap do Component em _app.js para capturar erros de qualquer página.

Anti-patterns

• Confiar só no dev overlay: ele não existe em produção; erros de cliente em produção exigem Error Boundary explícito.
• Expor detalhes de erro ao usuário via página 500 padrão: a página estática já evita isso por padrão, não sobrescrever com stack trace.

Key Takeaways

1. Três camadas distintas: dev overlay, servidor (500/404), cliente (Error Boundary).
2. Error Boundaries são componentes de classe (React ainda não tem hook equivalente).
3. Para monitorar erros de cliente em produção, usar serviço como Sentry, Bugsnag ou Datadog.
4. pages/500.js e pages/404.js são os pontos de customização server-side.

Connects To

• getServerSideProps (ch357): erro não tratado nele também cai em pages/500.js.
• Custom App (pages/_app.js): local onde o ErrorBoundary é montado globalmente.