Unexpected Application Error no React Router: como resolver (guia definitivo)

Se você é um desenvolvedor React, provavelmente já se deparou com o temido erro “Unexpected Application Error” ao trabalhar com o React Router. Esse erro genérico pode ser frustrante, pois nem sempre aponta diretamente para a causa raiz.

Mas entender como o React Router (principalmente a partir da versão 6.4) lida com erros é essencial para resolver isso de forma rápida.

---

🧠 Entendendo o erro

A partir do React Router 6.4, foi introduzido um novo sistema de tratamento de erros.

Quando ocorre um erro durante:

• carregamento de dados (loaders)
• envio de dados (actions)
• renderização de componentes

O React Router captura esse erro e mostra “Unexpected Application Error” se você não definiu um tratamento específico.

---

🚨 Causas mais comuns

1. Erros em loaders ou actions

São funções assíncronas executadas antes do render ou após um envio de formulário.

Se algo falhar (API, lógica, etc.), o erro é capturado.

👉 Se você não tiver um errorElement, aparece o erro genérico.

---

2. Erros na renderização de componentes

Se um componente quebra e não existe um ErrorBoundary adequado, o erro pode subir até o React Router.

---

3. Configuração incorreta

Erros simples também causam isso:

• ID de rota errado
• URL inválida
• dados inesperados

---

🛠️ Como resolver (na prática)

✅ 1. Usar errorElement nas rotas

Essa é a solução mais importante.

Você define um componente de erro que será exibido automaticamente.

import { createBrowserRouter, RouterProvider, useRouteError } from “react-router-dom”; function RootErrorElement() { const error = useRouteError(); console.error(error); return (

); } const router = createBrowserRouter([ { path: ”/”, element: , errorElement: , children: [ { path: “about”, element: , loader: async () => { throw new Response(“Dados não encontrados”, { status: 404 }); }, }, ], }, ]); function App() { return <RouterProvider router={router} />; }

👉 Isso substitui o erro genérico por algo controlado.

---

✅ 2. Tratar erros nos loaders e actions

Você pode lançar erros HTTP direto:

export async function loader({ params }) { const response = await fetch(`/api/posts/${params.postId}`); if (!response.ok) { throw new Response(“Erro ao carregar”, { status: response.status }); } return response.json(); }

Ou erros personalizados:

import { json } from “react-router-dom”; throw json( { message: “Usuário e senha obrigatórios” }, { status: 400 } );

---

✅ 3. Usar console.error

Sempre logue o erro:

console.error(error);

👉 Isso te mostra a causa real (muito importante no debug).

---

✅ 4. Verificar versões

Às vezes o problema é incompatibilidade:

npm install react-router-dom@latest

---

✅ 5. Usar ErrorBoundary (React puro)

Para erros fora do fluxo do React Router:

👉 combine com errorElement para cobertura total.

---

🧩 Conclusão

O erro “Unexpected Application Error” não é o problema — ele é só um sintoma.

👉 O real problema é não ter tratamento de erro definido.

Se você:

• usar errorElement
• tratar erros em loaders/actions
• debugar corretamente

👉 esse erro simplesmente deixa de ser um problema e vira algo controlado.