---
title: "Adicione um error boundary no React e registre os erros que ele deixa passar"
description: "Um error boundary do React captura erros durante o render e mostra um fallback. Veja a classe, os erros que ele deixa passar e como enviar cada um ao LogBrew, testados no React 19.3."
canonical: "https://logbrew.co/pt-BR/guides/react-error-boundary"
last_updated: "2026-11-21"
---

# Adicione um error boundary no React e registre os erros que ele deixa passar

Um error boundary do React captura erros durante o render e mostra um fallback. Veja a classe, os erros que ele deixa passar e como enviar cada um ao LogBrew, testados no React 19.3.

Testado em 21 de novembro de 2026 com React 19.3.1, Vite 8.3.8, Chrome 156, @logbrew/react 0.1.6, @logbrew/sdk 0.1.47 e logbrew CLI 0.1.96

Por [Furkan Erday](https://github.com/furkanerday). Furkan Erday é o fundador do LogBrew. Ele desenvolve o LogBrew com Claude Code e Codex todos os dias.

Canonical: https://logbrew.co/pt-BR/guides/react-error-boundary

## Quais erros do React mostram um fallback e chegam ao LogBrew

| Onde o erro foi lançado | Fallback mostrado | Problema no LogBrew |
| --- | --- | --- |
| Render, dentro de `LogBrewErrorBoundary` | Sim | Sim |
| `useEffect`, dentro do boundary | Sim | Sim |
| Render, sem boundary | Não, raiz vazia | Sim, pelas opções da raiz |
| Handler `onClick` | Não | Não |
| Handler async, depois de `await` | Não | Não |
| `onClick` com `captureReactError()` | Não | Sim |

6 erros em 1 build de produção do Vite com React 19.3.1 e @logbrew/react 0.1.6.

## Escreva um error boundary

### Escreva o boundary como componente de classe

O React não tem um hook para isso, então um error boundary é uma classe. `getDerivedStateFromError` troca para o fallback no render seguinte. `componentDidCatch` recebe o erro e `info.componentStack`, a lista de componentes acima do que lançou o erro.

```bash
import { Component } from "react";

export class ErrorBoundary extends Component {
  state = { error: null };

  static getDerivedStateFromError(error) {
    return { error };
  }

  componentDidCatch(error, info) {
    console.log("caught:", error.message);
    console.log("in:", info.componentStack.split("\n")[1].trim());
  }

  render() {
    if (this.state.error) return <p role="alert">Could not load the taps.</p>;
    return this.props.children;
  }
}
```

### Envolva a parte da página que pode falhar

`TapList` lê `taps.map` quando `taps` está ausente, então lança um erro durante o render. O boundary mostrou `Could not load the taps.`, e o título `Taproom` continuou na tela. Em desenvolvimento, o React também imprimiu o erro com `The above error occurred in the <TapList> component`.

```bash
// TapList.jsx
export function TapList({ taps }) {
  return <ul>{taps.map((tap) => <li key={tap}>{tap}</li>)}</ul>;
}

// App.jsx
import { ErrorBoundary } from "./ErrorBoundary.jsx";
import { TapList } from "./TapList.jsx";

export function App() {
  return (
    <main>
      <h1>Taproom</h1>
      <ErrorBoundary>
        <TapList />
      </ErrorBoundary>
    </main>
  );
}
```

Saída

```text
caught: Cannot read properties of undefined (reading 'map')
in: at TapList (http://127.0.0.1:25174/guide/TapList.jsx:3:27)
```

### Um erro num handler de evento passa direto pelo boundary

O React chama `onClick` fora do render, então o boundary nunca recebeu o erro. O botão continuou na página, e o navegador imprimiu um erro não capturado. Um erro depois de `await` fez o mesmo.

```bash
export function PourButton() {
  return (
    <button onClick={() => { throw new Error("pour failed"); }}>Pour</button>
  );
}

// main.jsx
createRoot(document.getElementById("root")).render(
  <ErrorBoundary>
    <PourButton />
  </ErrorBoundary>
);
```

Saída

```text
Uncaught Error: pour failed
    at onClick (http://127.0.0.1:25174/guide/PourButton.jsx:6:10)
```

### Passe o erro de um handler ao boundary pelo estado

Capture o erro no handler, guarde com `setError` e lance no render seguinte. Aí o boundary mostra o fallback e recebe o erro em `componentDidCatch`.

```bash
import { useState } from "react";

export function SafePourButton() {
  const [error, setError] = useState(null);
  if (error) throw error;

  function pour() {
    try {
      throw new Error("pour failed");
    } catch (caught) {
      setError(caught);
    }
  }

  return <button onClick={pour}>Pour</button>;
}
```

Saída

```text
caught: pour failed
in: at SafePourButton (http://127.0.0.1:25174/guide/SafePourButton.jsx:7:28)
```

### Sem boundary, o React remove a árvore inteira

Quando nenhum boundary captura um erro de render, o React 19 desmonta a raiz. O elemento `root` ficou vazio, e o título sumiu também. O React imprimiu o erro e um aviso que pede um error boundary.

```bash
import { createRoot } from "react-dom/client";
import { TapList } from "./TapList.jsx";

createRoot(document.getElementById("root")).render(
  <main>
    <h1>Taproom</h1>
    <TapList />
  </main>
);
```

Saída

```text
Uncaught TypeError: Cannot read properties of undefined (reading 'map')
An error occurred in the <TapList> component. Consider adding an error boundary to your tree to customize error handling behavior.
Visit https://react.dev/link/error-boundaries to learn more about error boundaries.
```

## Envie os erros do React ao LogBrew

### Instale os pacotes

`@logbrew/react` traz o provider, o error boundary e as opções da raiz. Use uma chave de navegador do seu projeto LogBrew como `clientKey`.

```bash
npm install @logbrew/sdk @logbrew/react react
```

### Crie o cliente e um transport

O cliente guarda os eventos numa fila até você chamar `client.flush(transport)`. O transport precisa devolver `{ statusCode }`. Quando o nosso devolveu a resposta do `fetch`, o flush falhou com `invalid transport response`. Defina `VITE_LOGBREW_ENDPOINT` como `https://api.logbrew.co/v1/events`. Nós enviamos para um servidor LogBrew local.

```bash
import { createLogBrewReactClient } from "@logbrew/react";

export const client = createLogBrewReactClient({
  clientKey: import.meta.env.VITE_LOGBREW_CLIENT_KEY
});

export const transport = {
  async send(apiKey, body) {
    const response = await fetch(import.meta.env.VITE_LOGBREW_ENDPOINT, {
      method: "POST",
      headers: {
        authorization: `Bearer ${apiKey}`,
        "content-type": "application/json",
      },
      body
    });
    return { statusCode: response.status };
  }
};

export function send() {
  return client
    .flush(transport)
    .then((result) => console.log("sent", JSON.stringify(result)));
}
```

### Coloque LogBrewErrorBoundary dentro de LogBrewProvider

`LogBrewErrorBoundary` pega o cliente de `LogBrewProvider`. Sem provider, ele mostrou o fallback mas não enviou nada, e `onCaptureError` recebeu `captureReactError requires a client`. `onError` roda depois da captura, então faça o flush ali.

```bash
import { LogBrewErrorBoundary, LogBrewProvider } from "@logbrew/react";
import { client, send } from "./logbrew.js";
import { TapList } from "./TapList.jsx";

export function App() {
  return (
    <LogBrewProvider client={client}>
      <LogBrewErrorBoundary
        fallback={({ error, resetError }) => (
          <div role="alert">
            <p>Could not load the taps: {error.message}</p>
            <button onClick={resetError}>Try Again</button>
          </div>
        )}
        onError={send}
      >
        <TapList />
      </LogBrewErrorBoundary>
    </LogBrewProvider>
  );
}
```

Saída

```text
sent {"statusCode":200,"attempts":1,"batches":1}
```

### Capture os erros que nenhum boundary capturou

`createLogBrewReactRootOptions()` dá a `createRoot` os callbacks de erro. Ele registrou o erro de render sem boundary. Ele ignora os erros que `LogBrewErrorBoundary` já enviou, então cada erro chega 1 vez só.

```bash
import { createRoot } from "react-dom/client";
import { createLogBrewReactRootOptions } from "@logbrew/react";
import { client, send } from "./logbrew.js";
import { TapList } from "./TapList.jsx";

createRoot(
  document.getElementById("root"),
  createLogBrewReactRootOptions(client, { onUncaughtError: send })
).render(<TapList />);
```

Saída

```text
sent {"statusCode":200,"attempts":1,"batches":1}
```

### Reporte erros de handlers com captureReactError()

Nem um boundary nem um callback da raiz recebe o erro de um handler, então capture o erro e passe para `captureReactError()`. Os `metadata` que você passa ficam no problema.

```bash
import { captureReactError } from "@logbrew/react";
import { client, send } from "./logbrew.js";

export function PayButton() {
  async function pay() {
    try {
      await Promise.resolve();
      throw new Error("payment declined");
    } catch (error) {
      captureReactError(client, error, { metadata: { action: "pay" } });
      send();
    }
  }

  return <button onClick={pay}>Pay</button>;
}
```

Saída

```text
sent {"statusCode":200,"attempts":1,"batches":1}
```

### Leia os problemas de volta

Lemos o projeto com uma chave de leitura. O erro de render dentro do boundary e o mesmo erro sem boundary vieram de `TapList.jsx`, então viraram 1 problema com 2 ocorrências. O erro do handler virou um problema separado.

```bash
logbrew issues --since 3h
```

Saída

```text
Issues (2)
- 1613a62e-31a3-5045-a144-c9c593760bff unresolved error priority=medium React error: payment declined occurrences=1 users=unknown last_seen=2026-11-21T06:35:49.154Z service=unknown_service trace=2ca253b519dfa2866268889760e5f2a0 assignee=unassigned [unversioned / production]
- f9eb7448-fab2-5d52-82f3-592a3b680a08 unresolved error priority=medium React error: Cannot read properties of undefined (reading 'map') occurrences=2 users=unknown last_seen=2026-11-21T06:35:43.870Z service=unknown_service trace=225e883023acc9c768da676fedd8e2c1 assignee=unassigned [unversioned / production]
```

## O que vimos no teste

Criamos 1 app Vite com React 19.3.1 e @logbrew/react 0.1.6, e rodamos cada caso no Chrome com um servidor LogBrew local. As saídas acima vêm do servidor de desenvolvimento do Vite. Rodamos os mesmos casos num build de produção, com os mesmos resultados.

Só os erros durante o render e em `useEffect` chegaram a um boundary. Os erros em `onClick` e depois de `await` não chegaram a nenhum boundary nem a nenhum callback da raiz. Só `captureReactError()` enviou esses erros.

|  | `LogBrewErrorBoundary` | `onUncaughtError` |
| --- | --- | --- |
| Erro de render dentro do boundary | Sim | Não |
| Erro de render sem boundary | Não | Sim |
| Erro num handler de evento | Não | Não |

## Reinicie o boundary e tente de novo

O fallback de `LogBrewErrorBoundary` recebe `resetError`, que renderiza os filhos de novo. Se o filho lançar o erro de novo, o boundary mostra o fallback outra vez e envia mais 1 evento.

Então corrija a causa antes de tentar de novo, por exemplo carregue os dados de novo. No nosso teste, a nova tentativa renderizou a lista quando os dados estavam lá.

|  | Fallback mostrado | Evento enviado |
| --- | --- | --- |
| Primeiro erro de render | Sim | Sim |
| `Try Again`, o filho falha de novo | Sim | Sim |
| `Try Again`, o filho renderiza | Não | Não |

## O que o LogBrew registra

Cada erro do React vira um problema com o título `React error:` e a mensagem. O boundary registra o mecanismo `react.error_boundary` com `handled: true`. As opções da raiz registram `react.uncaught_error` com `handled: false`.

O LogBrew agrupa os erros do React pelo tipo do erro e pelo arquivo do primeiro frame da pilha. No nosso build de produção, 5 eventos `Error` com mensagens diferentes, como `keg sensor offline` e `tap list not loaded`, vieram de 1 arquivo do bundle e viraram 1 problema. Em desenvolvimento, cada componente é um arquivo próprio, então os problemas ficaram separados.

- `LogBrewErrorBoundary`
  - `mechanism`: `react.error_boundary`
  - `handled`: `true`
  - Problema: `React error: Cannot read properties of undefined (reading 'map')`
- `createLogBrewReactRootOptions()`
  - `mechanism`: `react.uncaught_error`
  - `handled`: `false`
  - Frames de stack: 10
- `captureReactError()`
  - Problema: `React error: payment declined`
  - `metadata.action`: `pay`
  - Chave de agrupamento: `react.error:Error:…/HandlerButton.jsx`

## Perguntas frequentes

### O que é um error boundary no React?

Um componente de classe com `getDerivedStateFromError` ou `componentDidCatch`. Quando um filho lança um erro durante o render, o React mostra o fallback do boundary e mantém o resto da página.

### Dá para escrever um error boundary com hooks?

Não. O React não tem um hook para isso, então o boundary é uma classe. Escreva 1 vez, ou use `LogBrewErrorBoundary`, e coloque em volta dos componentes de função.

### Por que meu error boundary não captura o erro?

O erro foi lançado fora do render, muitas vezes num handler de evento ou depois de `await`. Capture o erro ali e reporte com `captureReactError()`, ou guarde no estado e lance durante o render.

### Onde coloco os error boundaries?

Em volta de cada parte da página que pode falhar sozinha, como uma lista que carrega dados, para o resto da página continuar. Coloque também 1 perto da raiz, porque um erro que nenhum boundary captura remove a árvore inteira.

### Como registro os erros de um error boundary?

Envie os erros a partir de `componentDidCatch`, ou use `LogBrewErrorBoundary` dentro de `LogBrewProvider`. Adicione `createLogBrewReactRootOptions()` ao `createRoot` para os erros que nenhum boundary capturou.

## Veja cada erro do React com a pilha de componentes

O LogBrew registra cada erro de render do React com a pilha de componentes e agrupa as repetições em 1 problema. Comece no plano gratuito generoso, sem cartão.

[Comece grátis](https://logbrew.co/pt-BR)

## Fontes

- [React docs, Catching rendering errors with an Error Boundary](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary)
- [React docs, createRoot parameters](https://react.dev/reference/react-dom/client/createRoot#parameters)
- [reactjs/react.dev#8157](https://github.com/reactjs/react.dev/issues/8157)

## Mais guias para agentes, Python, Node.js e React

- [Adicione um servidor MCP ao Claude Code e ao Codex](https://logbrew.co/pt-BR/guides/mcp-server-claude-code-codex)
- [Use AGENTS.md no Claude Code e no Codex](https://logbrew.co/pt-BR/guides/agents-md)
- [Corrija o erro 529 overloaded e o erro 429 de rate limit do Claude](https://logbrew.co/pt-BR/guides/claude-overloaded-rate-limit-error)
- [Configure o Python logging com os níveis de log certos e captura de exceções](https://logbrew.co/pt-BR/guides/python-logging)
- [Structured logging com formato de log e níveis que você busca por campo](https://logbrew.co/pt-BR/guides/structured-logging)
- [Configure o logging em Node.js com Pino ou Winston sem perder nenhum erro](https://logbrew.co/pt-BR/guides/node-logging)
- [Configure o logging do Django e guarde o stack trace de cada erro 500](https://logbrew.co/pt-BR/guides/django-logging)
- [Configure o logging do FastAPI e trate os erros sem perder o stack trace](https://logbrew.co/pt-BR/guides/fastapi-logging)
- [Trace ID vs span ID, decodificados de um header traceparent real](https://logbrew.co/pt-BR/guides/trace-id)
- [Corrija Minified React error #418 e #185 com a mensagem completa e a sua linha de código](https://logbrew.co/pt-BR/errors/minified-react-error)
- [Guias de erros, logs, traces, métricas e versões](https://logbrew.co/pt-BR/guides)
