Tratamento de Erros

Q: O error.tsx pode capturar erros lançados no layout.tsx do mesmo nível?

Não. error.tsx só captura erros nos filhos do segmento da rota. Para capturar erros de layout, coloque error.tsx no segmento pai. Para erros de layout raiz, use global-error.tsx.

Q: Por que global-error.tsx precisa de suas próprias tags e ?

Quando global-error.tsx é ativado, ele substitui todo o layout raiz. Sem seu próprio e , a página não teria estrutura de documento. Isso só ativa em produção; o desenvolvimento mostra a sobreposição de erros do Next.js.

Q: Armadilha: O que acontece se você envolver redirect() em um try/catch dentro de um Componente Servidor?

redirect() lança um erro especial NEXT_REDIRECT. Um try/catch capturará e engolirá esse erro, impedindo o redirecionamento. Ou relance os erros NEXT_REDIRECT ou chame redirect() fora do bloco try/catch.

Q: Quando você deve usar throw em vez de retornar um objeto de erro em uma Server Action?

Use throw para falhas inesperadas que devem acionar o limite de erro mais próximo. Retorne um objeto de erro tipado ({ success: false; error: string }) para erros de validação esperados. Isso dá ao cliente controle granular sobre como exibir mensagens de validação.

Q: O que a função reset faz e quando ela falha?

reset() re-renderiza os filhos do limite de erro, tentando a recuperação. Funciona para erros transitórios como timeouts de rede. Não corrige bugs persistentes; o mesmo erro será lançado novamente na re-renderização.

Q: Como você tiparia o resultado de uma Server Action como uma união discriminada em TypeScript?

O discriminador success permite que o TypeScript restrinja o tipo ao verificar o resultado.

Q: Como você tipa a prop error em error.tsx com TypeScript?

Error & { digest?: string } é o tipo necessário. O digest é opcional.

Receita

Trate erros graciosamente no App Router do Next.js 15+ usando limites de erro error.tsx, global-error.tsx para falhas no nível raiz, not-found.tsx para 404s e logging estruturado.

Exemplo de Trabalho

Limite de Erro em Nível de Rota

// app/dashboard/error.tsx
"use client";
 
import { useEffect } from "react";
 
export default function DashboardError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  useEffect(() => {
    // Registre em seu serviço de relatórios de erros
    console.error("Erro no Dashboard:", error);
  }, [error]);
 
  return (
    <div role="alert">
      <h2>Ocorreu um erro</h2>
      <p>{error.message}</p>
      {error.digest && (
        <p className="text-sm text-gray-500">ID do Erro: {error.digest}</p>
      )}
      <button onClick={reset}>Tentar novamente</button>
    </div>
  );
}

Manipulador de Erro Global

// app/global-error.tsx
"use client";
 
export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  return (
    <html>
      <body>
        <div role="alert">
          <h1>Erro na Aplicação</h1>
          <p>Ocorreu um erro inesperado.</p>
          <button onClick={reset}>Recarregar</button>
        </div>
      </body>
    </html>
  );
}

Página Não Encontrada

// app/not-found.tsx
import Link from "next/link";
 
export default function NotFound() {
  return (
    <div>
      <h1>404 - Página Não Encontrada</h1>
      <p>A página que você procura não existe.</p>
      <Link href="/">Ir para a página inicial</Link>
    </div>
  );
}

Não Encontrado Programático em Componentes Servidor

// app/posts/[slug]/page.tsx
import { notFound } from "next/navigation";
 
export default async function PostPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const post = await db.post.findUnique({ where: { slug } });
 
  if (!post) {
    notFound(); // Renderiza o not-found.tsx mais próximo
  }
 
  return <article>{post.content}</article>;
}

Utilitário de Logging de Erros

// lib/logger.ts
type ErrorContext = {
  userId?: string;
  path?: string;
  action?: string;
  metadata?: Record<string, unknown>;
};
 
export function logError(error: unknown, context?: ErrorContext) {
  const errorObj = error instanceof Error ? error : new Error(String(error));
 
  const payload = {
    message: errorObj.message,
    stack: errorObj.stack,
    timestamp: new Date().toISOString(),
    ...context,
  };
 
  // Substitua por Sentry, Axiom ou seu serviço preferido
  if (process.env.NODE_ENV === "production") {
    fetch("/api/log", {
      method: "POST",
      body: JSON.stringify(payload),
    }).catch(() => {
      // Engole erros de logging para prevenir falhas em cascata
    });
  } else {
    console.error("[Erro]", payload);
  }
}

Tratamento de Erros de Server Action

// app/actions.ts
"use server";
 
import { logError } from "@/lib/logger";
 
type ActionResult<T> =
  | { success: true; data: T }
  | { success: false; error: string };
 
export async function createPost(
  formData: FormData
): Promise<ActionResult<{ id: string }>> {
  try {
    const title = formData.get("title") as string;
 
    if (!title) {
      return { success: false, error: "O título é obrigatório" };
    }
 
    const post = await db.post.create({ data: { title } });
    return { success: true, data: { id: post.id } };
  } catch (error) {
    logError(error, { action: "createPost" });
    return { success: false, error: "Falha ao criar post" };
  }
}

Análise Detalhada

Como Funciona

error.tsx é um Componente Cliente que envolve os filhos do segmento da rota em um Limite de Erro do React. Ele captura erros lançados durante a renderização, em Componentes Servidor e durante a busca de dados.
global-error.tsx captura erros no layout raiz. Ele deve renderizar suas próprias tags <html> e <body> porque substitui todo o layout raiz quando ativado.
not-found.tsx é renderizado quando notFound() é chamado ou quando nenhuma rota corresponde. O not-found.tsx mais próximo na árvore de componentes é usado.
Limites de erro não capturam erros em manipuladores de eventos, limpeza de useEffect ou código assíncrono em Componentes Cliente. Use try/catch para esses.
A propriedade digest é um hash gerado pelo Next.js para erros do lado do servidor. Ele permite correlacionar erros voltados para o usuário com logs do servidor sem expor traces de pilha confidenciais.
A função reset tenta re-renderizar os filhos do limite de erro. Funciona para erros transitórios (problemas de rede), mas não para bugs persistentes.

Variações

Limite de Erro com Tentativa e Fallback:

"use client";
 
import { useEffect, useState } from "react";
 
export default function ErrorWithRetry({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  const [retryCount, setRetryCount] = useState(0);
 
  useEffect(() => {
    if (retryCount > 0) {
      reset();
    }
  }, [retryCount, reset]);
 
  if (retryCount >= 3) {
    return (
      <div>
        <h2>Erro Persistente</h2>
        <p>Por favor, contate o suporte. ID do Erro: {error.digest}</p>
      </div>
    );
  }
 
  return (
    <div role="alert">
      <h2>Ocorreu um Erro</h2>
      <button onClick={() => setRetryCount((c) => c + 1)}>
        Tentar novamente ({3 - retryCount} tentativas restantes)
      </button>
    </div>
  );
}

Tratamento de Erros de Route Handler:

// app/api/posts/route.ts
import { NextRequest, NextResponse } from "next/server";
import { logError } from "@/lib/logger";
 
export async function GET(request: NextRequest) {
  try {
    const posts = await db.post.findMany();
    return NextResponse.json(posts);
  } catch (error) {
    logError(error, { path: "/api/posts", action: "GET" });
    return NextResponse.json(
      { error: "Erro interno do servidor" },
      { status: 500 }
    );
  }
}

Notas de TypeScript

O tipo da prop error é Error & { digest?: string }. O digest é opcional e só está presente para erros do lado do servidor.
Server Actions devem retornar uma união discriminada ({ success: true; data: T } | { success: false; error: string }) para tratamento de erros type-safe no cliente.
Evite usar throw em Server Actions para erros de validação. Reserve throw para falhas inesperadas que devem acionar o limite de erro.

Armadilhas

error.tsx deve ser um Componente Cliente. Requer a diretiva "use client". Esquecer isso gera um erro de build.
error.tsx não captura erros no layout.tsx do mesmo nível. Para capturar erros de layout, coloque error.tsx no segmento pai, ou use global-error.tsx para o layout raiz.
global-error.tsx só ativa em produção. Em desenvolvimento, a sobreposição de erros do Next.js é mostrada em vez disso.
redirect() lança um erro especial. Se você envolver redirect() em um try/catch dentro de um Componente Servidor, o redirecionamento será capturado e engolido. Ou relance os erros NEXT_REDIRECT ou chame redirect() fora do try/catch.
Detalhes de erro do lado do servidor são ocultados em produção. O Next.js remove traces de pilha e mensagens de erros mostrados ao cliente. Use o digest para correlacionar com logs do servidor.

Alternativas

Abordagem	Prós	Contras
Limite `error.tsx`	Embutido, automático, por rota	Apenas Componente Cliente, sem erros de layout
`global-error.tsx`	Captura erros do layout raiz	Deve renderizar seu próprio html/body, apenas produção
Try/catch em Server Actions	Controle granular, retorna erros tipados	Manual, sem limite automático
Sentry ou Datadog	Rastreamento rico de erros, alertas	Dependência externa, custo
Classe `ErrorBoundary` do React	Controle total, reutilizável	Verboso, sem erros de Componente Servidor

FAQs

Por que `error.tsx` deve ser um Componente Cliente?

Limites de Erro do React são um conceito do lado do cliente que dependem de métodos de ciclo de vida de componentes de classe.
A diretiva "use client" é necessária para que error.tsx funcione como um limite de erro.
Esquecer a diretiva gera um erro de build.

Qual é a propriedade `digest` no objeto de erro?

É um hash gerado pelo Next.js para erros do lado do servidor.
Permite correlacionar erros voltados para o usuário com logs do servidor sem expor traces de pilha.
Só está presente em erros que se originaram no servidor.

O `error.tsx` pode capturar erros lançados no `layout.tsx` do mesmo nível?

Não. error.tsx só captura erros nos filhos do segmento da rota.
Para capturar erros de layout, coloque error.tsx no segmento pai.
Para erros de layout raiz, use global-error.tsx.

Por que `global-error.tsx` precisa de suas próprias tags `` e ``?

Quando global-error.tsx é ativado, ele substitui todo o layout raiz.
Sem seu próprio <html> e <body>, a página não teria estrutura de documento.
Isso só ativa em produção; o desenvolvimento mostra a sobreposição de erros do Next.js.

Armadilha: O que acontece se você envolver `redirect()` em um try/catch dentro de um Componente Servidor?

redirect() lança um erro especial NEXT_REDIRECT.
Um try/catch capturará e engolirá esse erro, impedindo o redirecionamento.
Ou relance os erros NEXT_REDIRECT ou chame redirect() fora do bloco try/catch.

Quando você deve usar `throw` em vez de retornar um objeto de erro em uma Server Action?

Use throw para falhas inesperadas que devem acionar o limite de erro mais próximo.
Retorne um objeto de erro tipado ({ success: false; error: string }) para erros de validação esperados.
Isso dá ao cliente controle granular sobre como exibir mensagens de validação.

O que a função `reset` faz e quando ela falha?

reset() re-renderiza os filhos do limite de erro, tentando a recuperação.
Funciona para erros transitórios como timeouts de rede.
Não corrige bugs persistentes; o mesmo erro será lançado novamente na re-renderização.

Como você tiparia o resultado de uma Server Action como uma união discriminada em TypeScript?

type ActionResult<T> =
  | { success: true; data: T }
  | { success: false; error: string };
 
export async function createPost(
  formData: FormData
): Promise<ActionResult<{ id: string }>> {
  // ...
}

O discriminador success permite que o TypeScript restrinja o tipo ao verificar o resultado.

Como você tipa a prop `error` em `error.tsx` com TypeScript?

export default function DashboardError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  // ...
}

Error & { digest?: string } é o tipo necessário. O digest é opcional.

Por que o utilitário de logging de erros engole seus próprios erros de fetch?

Se o próprio serviço de logging estiver inativo, um erro lançado poderia causar uma cascata e mascarar o erro original.
Usar .catch(() => {}) garante que as falhas de logging sejam silenciosas.
Isso evita que um logger quebrado derrube toda a aplicação.

Armadilha: Por que os detalhes de erro do lado do servidor são ocultados do cliente em produção?

O Next.js remove traces de pilha e mensagens de erro para evitar vazar detalhes de implementação sensíveis.
Apenas o hash digest é exposto, que você pode usar para encontrar o erro completo nos logs do servidor.
Em desenvolvimento, a sobreposição de erro completa é mostrada em vez disso.

Quais erros `error.tsx` NÃO captura?

Erros em manipuladores de eventos e funções de limpeza de useEffect.
Erros em código assíncrono dentro de Componentes Cliente (a menos que capturados manualmente).
Erros no layout.tsx do mesmo nível.
Use try/catch para manipuladores de eventos e global-error.tsx para falhas de layout raiz.

Relacionado

Autenticação - tratamento de falhas de autenticação
Route Handlers de API - respostas de erro em Route Handlers
Testes - testando estados de erro
Documentação de Tratamento de Erros do Next.js

// app/dashboard/error.tsx
"use client";
 
import { useEffect } from "react";
 
export default function DashboardError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  useEffect(() => {
    // Registre em seu serviço de relatórios de erros
    console.error("Erro no Dashboard:", error);
  }, [error]);
 
  return (
    <div role="alert">
      <h2>Ocorreu um erro</h2>
      <p>{error.message}</p>
      {error.digest && (
        <p className="text-sm text-gray-500">ID do Erro: {error.digest}</p>
      )}
      <button onClick={reset}>Tentar novamente</button>
    </div>
  );
}

Manipulador de Erro Global

// app/global-error.tsx
"use client";
 
export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  return (
    <html>
      <body>
        <div role="alert">
          <h1>Erro na Aplicação</h1>
          <p>Ocorreu um erro inesperado.</p>
          <button onClick={reset}>Recarregar</button>
        </div>
      </body>
    </html>
  );
}

Página Não Encontrada

// app/not-found.tsx
import Link from "next/link";
 
export default function NotFound() {
  return (
    <div>
      <h1>404 - Página Não Encontrada</h1>
      <p>A página que você procura não existe.</p>
      <Link href="/">Ir para a página inicial</Link>
    </div>
  );
}

Não Encontrado Programático em Componentes Servidor

// app/posts/[slug]/page.tsx
import { notFound } from "next/navigation";
 
export default async function PostPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const post = await db.post.findUnique({ where: { slug } });
 
  if (!post) {
    notFound(); // Renderiza o not-found.tsx mais próximo
  }
 
  return <article>{post.content}</article>;
}

Utilitário de Logging de Erros

// lib/logger.ts
type ErrorContext = {
  userId?: string;
  path?: string;
  action?: string;
  metadata?: Record<string, unknown>;
};
 
export function logError(error: unknown, context?: ErrorContext) {
  const errorObj = error instanceof Error ? error : new Error(String(error));
 
  const payload = {
    message: errorObj.message,
    stack: errorObj.stack,
    timestamp: new Date().toISOString(),
    ...context,
  };
 
  // Substitua por Sentry, Axiom ou seu serviço preferido
  if (process.env.NODE_ENV === "production") {
    fetch("/api/log", {
      method: "POST",
      body: JSON.stringify(payload),
    }).catch(() => {
      // Engole erros de logging para prevenir falhas em cascata
    });
  } else {
    console.error("[Erro]", payload);
  }
}

Tratamento de Erros de Server Action

// app/actions.ts
"use server";
 
import { logError } from "@/lib/logger";
 
type ActionResult<T> =
  | { success: true; data: T }
  | { success: false; error: string };
 
export async function createPost(
  formData: FormData
): Promise<ActionResult<{ id: string }>> {
  try {
    const title = formData.get("title") as string;
 
    if (!title) {
      return { success: false, error: "O título é obrigatório" };
    }
 
    const post = await db.post.create({ data: { title } });
    return { success: true, data: { id: post.id } };
  } catch (error) {
    logError(error, { action: "createPost" });
    return { success: false, error: "Falha ao criar post" };
  }
}

Análise Detalhada

Como Funciona

error.tsx é um Componente Cliente que envolve os filhos do segmento da rota em um Limite de Erro do React. Ele captura erros lançados durante a renderização, em Componentes Servidor e durante a busca de dados.
global-error.tsx captura erros no layout raiz. Ele deve renderizar suas próprias tags <html> e <body> porque substitui todo o layout raiz quando ativado.
not-found.tsx é renderizado quando notFound() é chamado ou quando nenhuma rota corresponde. O not-found.tsx mais próximo na árvore de componentes é usado.
Limites de erro não capturam erros em manipuladores de eventos, limpeza de useEffect ou código assíncrono em Componentes Cliente. Use try/catch para esses.
A propriedade digest é um hash gerado pelo Next.js para erros do lado do servidor. Ele permite correlacionar erros voltados para o usuário com logs do servidor sem expor traces de pilha confidenciais.
A função reset tenta re-renderizar os filhos do limite de erro. Funciona para erros transitórios (problemas de rede), mas não para bugs persistentes.

Variações

Limite de Erro com Tentativa e Fallback:

"use client";
 
import { useEffect, useState } from "react";
 
export default function ErrorWithRetry({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  const [retryCount, setRetryCount] = useState(0);
 
  useEffect(() => {
    if (retryCount > 0) {
      reset();
    }
  }, [retryCount, reset]);
 
  if (retryCount >= 3) {
    return (
      <div>
        <h2>Erro Persistente</h2>
        <p>Por favor, contate o suporte. ID do Erro: {error.digest}</p>
      </div>
    );
  }
 
  return (
    <div role="alert">
      <h2>Ocorreu um Erro</h2>
      <button onClick={() => setRetryCount((c) => c + 1)}>
        Tentar novamente ({3 - retryCount} tentativas restantes)
      </button>
    </div>
  );
}

Tratamento de Erros de Route Handler:

// app/api/posts/route.ts
import { NextRequest, NextResponse } from "next/server";
import { logError } from "@/lib/logger";
 
export async function GET(request: NextRequest) {
  try {
    const posts = await db.post.findMany();
    return NextResponse.json(posts);
  } catch (error) {
    logError(error, { path: "/api/posts", action: "GET" });
    return NextResponse.json(
      { error: "Erro interno do servidor" },
      { status: 500 }
    );
  }
}

Notas de TypeScript

O tipo da prop error é Error & { digest?: string }. O digest é opcional e só está presente para erros do lado do servidor.
Server Actions devem retornar uma união discriminada ({ success: true; data: T } | { success: false; error: string }) para tratamento de erros type-safe no cliente.
Evite usar throw em Server Actions para erros de validação. Reserve throw para falhas inesperadas que devem acionar o limite de erro.

Armadilhas

error.tsx deve ser um Componente Cliente. Requer a diretiva "use client". Esquecer isso gera um erro de build.
error.tsx não captura erros no layout.tsx do mesmo nível. Para capturar erros de layout, coloque error.tsx no segmento pai, ou use global-error.tsx para o layout raiz.
global-error.tsx só ativa em produção. Em desenvolvimento, a sobreposição de erros do Next.js é mostrada em vez disso.
redirect() lança um erro especial. Se você envolver redirect() em um try/catch dentro de um Componente Servidor, o redirecionamento será capturado e engolido. Ou relance os erros NEXT_REDIRECT ou chame redirect() fora do try/catch.
Detalhes de erro do lado do servidor são ocultados em produção. O Next.js remove traces de pilha e mensagens de erros mostrados ao cliente. Use o digest para correlacionar com logs do servidor.

Alternativas

Abordagem	Prós	Contras
Limite `error.tsx`	Embutido, automático, por rota	Apenas Componente Cliente, sem erros de layout
`global-error.tsx`	Captura erros do layout raiz	Deve renderizar seu próprio html/body, apenas produção
Try/catch em Server Actions	Controle granular, retorna erros tipados	Manual, sem limite automático
Sentry ou Datadog	Rastreamento rico de erros, alertas	Dependência externa, custo
Classe `ErrorBoundary` do React	Controle total, reutilizável	Verboso, sem erros de Componente Servidor

FAQs

Por que `error.tsx` deve ser um Componente Cliente?

Limites de Erro do React são um conceito do lado do cliente que dependem de métodos de ciclo de vida de componentes de classe.
A diretiva "use client" é necessária para que error.tsx funcione como um limite de erro.
Esquecer a diretiva gera um erro de build.

Qual é a propriedade `digest` no objeto de erro?

É um hash gerado pelo Next.js para erros do lado do servidor.
Permite correlacionar erros voltados para o usuário com logs do servidor sem expor traces de pilha.
Só está presente em erros que se originaram no servidor.

O `error.tsx` pode capturar erros lançados no `layout.tsx` do mesmo nível?

Não. error.tsx só captura erros nos filhos do segmento da rota.
Para capturar erros de layout, coloque error.tsx no segmento pai.
Para erros de layout raiz, use global-error.tsx.

Por que `global-error.tsx` precisa de suas próprias tags `` e ``?

Quando global-error.tsx é ativado, ele substitui todo o layout raiz.
Sem seu próprio <html> e <body>, a página não teria estrutura de documento.
Isso só ativa em produção; o desenvolvimento mostra a sobreposição de erros do Next.js.

Armadilha: O que acontece se você envolver `redirect()` em um try/catch dentro de um Componente Servidor?

redirect() lança um erro especial NEXT_REDIRECT.
Um try/catch capturará e engolirá esse erro, impedindo o redirecionamento.
Ou relance os erros NEXT_REDIRECT ou chame redirect() fora do bloco try/catch.

Quando você deve usar `throw` em vez de retornar um objeto de erro em uma Server Action?

Use throw para falhas inesperadas que devem acionar o limite de erro mais próximo.
Retorne um objeto de erro tipado ({ success: false; error: string }) para erros de validação esperados.
Isso dá ao cliente controle granular sobre como exibir mensagens de validação.

O que a função `reset` faz e quando ela falha?

reset() re-renderiza os filhos do limite de erro, tentando a recuperação.
Funciona para erros transitórios como timeouts de rede.
Não corrige bugs persistentes; o mesmo erro será lançado novamente na re-renderização.

Como você tiparia o resultado de uma Server Action como uma união discriminada em TypeScript?

type ActionResult<T> =
  | { success: true; data: T }
  | { success: false; error: string };
 
export async function createPost(
  formData: FormData
): Promise<ActionResult<{ id: string }>> {
  // ...
}

O discriminador success permite que o TypeScript restrinja o tipo ao verificar o resultado.

Como você tipa a prop `error` em `error.tsx` com TypeScript?

export default function DashboardError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  // ...
}

Error & { digest?: string } é o tipo necessário. O digest é opcional.

Por que o utilitário de logging de erros engole seus próprios erros de fetch?

Se o próprio serviço de logging estiver inativo, um erro lançado poderia causar uma cascata e mascarar o erro original.
Usar .catch(() => {}) garante que as falhas de logging sejam silenciosas.
Isso evita que um logger quebrado derrube toda a aplicação.

Armadilha: Por que os detalhes de erro do lado do servidor são ocultados do cliente em produção?

O Next.js remove traces de pilha e mensagens de erro para evitar vazar detalhes de implementação sensíveis.
Apenas o hash digest é exposto, que você pode usar para encontrar o erro completo nos logs do servidor.
Em desenvolvimento, a sobreposição de erro completa é mostrada em vez disso.

Quais erros `error.tsx` NÃO captura?

Erros em manipuladores de eventos e funções de limpeza de useEffect.
Erros em código assíncrono dentro de Componentes Cliente (a menos que capturados manualmente).
Erros no layout.tsx do mesmo nível.
Use try/catch para manipuladores de eventos e global-error.tsx para falhas de layout raiz.

Relacionado

Autenticação - tratamento de falhas de autenticação
Route Handlers de API - respostas de erro em Route Handlers
Testes - testando estados de erro
Documentação de Tratamento de Erros do Next.js

Tratamento de Erros

Buscar na documentação

Tratamento de Erros