Capítulo 348 de 456

Custom Errors

Core Idea

Next.js gera páginas 404/500 estáticas por padrão; pages/404.js, pages/500.js e pages/_error.js permitem customizá-las no Pages Router.

Key Concepts

  • pages/404.js: página 404 customizada, gerada estaticamente em build time; aceita getStaticProps.
  • pages/500.js: página 500 customizada, também estática em build time; aceita getStaticProps.
  • pages/_error.js: componente Error reservado que trata erros 500 tanto client quanto server-side; só é usado em produção (dev mostra stack trace).
  • Error.getInitialProps: recebe { res, err } e retorna { statusCode }.
  • next/error: importa o componente Error built-in para reuso, aceitando props statusCode e title.

Code Examples

export default function Custom404() {
  return <h1>404 - Page Not Found</h1>
}
  • O que demonstra: 404 customizado mínimo.
function Error({ statusCode }) {
  return (
    <p>
      {statusCode
        ? `An error ${statusCode} occurred on server`
        : 'An error occurred on client'}
    </p>
  )
}

Error.getInitialProps = ({ res, err }) => {
  const statusCode = res ? res.statusCode : err ? err.statusCode : 404
  return { statusCode }
}

export default Error
  • O que demonstra: pages/_error.js customizado, unificando tratamento de erro client e server.
import Error from 'next/error'

export async function getServerSideProps() {
  const res = await fetch('https://api.github.com/repos/vercel/next.js')
  const errorCode = res.ok ? false : res.status
  const json = await res.json()
  return { props: { errorCode, stars: json.stargazers_count } }
}

export default function Page({ errorCode, stars }) {
  if (errorCode) {
    return <Error statusCode={errorCode} />
  }
  return <div>Next stars: {stars}</div>
}
  • O que demonstra: reuso do componente Error built-in dentro de uma página com getServerSideProps.

Anti-patterns

  • Esperar getStaticProps/getServerSideProps em _error.js: não é suportado.
  • Acessar /_error diretamente: _error é pathname reservado (como _app); acesso direto via routing renderiza 404.

Key Takeaways

  1. 404 e 500 padrão do Next.js seguem prefers-color-scheme do SO; arquivos custom em pages/404.js/500.js herdam o tema global via _app.
  2. pages/_error.js só roda em produção; em dev o erro real com stack trace é mostrado.
  3. next/error permite reaproveitar a página de erro built-in dentro de qualquer página, passando statusCode manualmente.

Connects To

  • custom-app: _error renderiza dentro do _app, por isso herda tema/estilos globais.
  • getServerSideProps / getStaticProps: usados para alimentar dados nas páginas de erro customizadas.
AnteriorAPI RoutesPróximoRendering