Error Boundary в React

Error Boundary (граница ошибок) в React — компонент, который ловит ошибку при отрисовке своих потомков и показывает запасной интерфейс вместо упавшего дерева. Без него одна ошибка в любом компоненте размонтирует всё приложение, и посетитель увидит белую страницу.

Ниже — что Error Boundary ловит и чего не ловит, как написать свой, когда взять библиотеку react-error-boundary, что изменилось в React 19 и как отправлять пойманные ошибки в мониторинг, чтобы о них узнавали вы, а не служба поддержки.

Что такое Error Boundary в React

Начиная с React 16 необработанная ошибка при рендере размонтирует всё дерево от корня. Логика простая: лучше пустой экран, чем интерфейс в неконсистентном состоянии, где кнопка «Оплатить» показывает чужую сумму.

Error Boundary ограничивает ущерб. Если упал компонент внутри границы, React заменит на запасной интерфейс только эту часть, а остальное приложение продолжит работать. Обычно ставят одну границу вокруг всего приложения — «Что-то пошло не так, обновите страницу» — и несколько локальных: вокруг виджета, боковой панели, отдельной страницы маршрута.

Что ловит Error Boundary и чего не ловит

Граница ловит ошибки, которые React видит в процессе отрисовки дерева под ней:

  • в render и теле функциональных компонентов;
  • в конструкторах и методах жизненного цикла классов;
  • в useEffect, useLayoutEffect и других хуках;
  • при загрузке lazy-компонента внутри Suspense, например ChunkLoadError после выкладки.

Не ловит:

Ошибка Почему Что делать
В обработчиках событий (onClick, onSubmit) обработчик вызывается не во время рендера try/catch внутри обработчика
В асинхронном коде: setTimeout, fetch().then, async-функции код выполняется после того, как рендер закончился try/catch с await, .catch() у промиса
При серверном рендеринге (SSR) границы работают только в браузере обработка ошибок на сервере
В самой границе граница не может поймать собственную ошибку ошибка уходит к ближайшей границе выше

Ошибку из обработчика или асинхронного кода можно отдать границе вручную: сохраните её в состоянии и бросьте при следующем рендере.

tsx
const [error, setError] = useState<unknown>(null);
if (error) throw error; // теперь ошибку поймает ближайшая граница

async function onSave() {
  try {
    await saveOrder();
  } catch (e) {
    setError(e);
  }
}

В React 19 так же к ближайшей границе доходит ошибка из асинхронной функции, переданной в startTransition.

Пример Error Boundary на классовом компоненте

Хука для границы ошибок в React нет — нужен классовый компонент с одним или двумя методами:

  • static getDerivedStateFromError(error) — возвращает новое состояние, чтобы показать запасной интерфейс;
  • componentDidCatch(error, info) — побочные действия: запись в лог или отправка в мониторинг. В info.componentStack — цепочка компонентов до упавшего.
tsx
import { Component, type ErrorInfo, type ReactNode } from 'react';

type Props = { fallback: ReactNode; children: ReactNode };
type State = { hasError: boolean };

export class ErrorBoundary extends Component<Props, State> {
  state: State = { hasError: false };

  static getDerivedStateFromError(): State {
    return { hasError: true };
  }

  componentDidCatch(error: Error, info: ErrorInfo) {
    console.error(error, info.componentStack);
  }

  render() {
    return this.state.hasError ? this.props.fallback : this.props.children;
  }
}
tsx
<ErrorBoundary fallback={<p>Не удалось загрузить отчёт.</p>}>
  <Report />
</ErrorBoundary>

В режиме разработки React всё равно показывает пойманную ошибку в консоли и в оверлее сборщика. Это нормально: в собранном приложении посетитель увидит только fallback.

react-error-boundary

Чтобы не писать класс самому, берут библиотеку react-error-boundary. Она умеет то, что в простом примере пришлось бы дописывать: сброс ошибки, сброс по смене ключей, хук для асинхронного кода.

tsx
import { ErrorBoundary, useErrorBoundary } from 'react-error-boundary';

function Fallback({ error, resetErrorBoundary }) {
  return (
    <div role="alert">
      <p>Что-то пошло не так.</p>
      <button onClick={resetErrorBoundary}>Попробовать снова</button>
    </div>
  );
}

<ErrorBoundary FallbackComponent={Fallback} resetKeys={[userId]}>
  <Profile userId={userId} />
</ErrorBoundary>;

resetKeys сбрасывает ошибку, когда меняется значение: пользователь открыл другой профиль — граница пробует отрисовать его заново. Хук useErrorBoundary даёт функцию showBoundary(error): вызовите её в catch асинхронного кода, и ошибка уйдёт к границе.

onUncaughtError и onCaughtError в React 19

В React 19 у createRoot появились обработчики ошибок всего приложения:

  • onUncaughtError — ошибка, которую не поймала ни одна граница: дерево размонтировано;
  • onCaughtError — ошибка, которую поймала граница и показала fallback;
  • onRecoverableError — ошибка, после которой React восстановился сам (например, расхождение при гидратации).
tsx
createRoot(document.getElementById('root')!, {
  onUncaughtError: (error, info) => report(error, info.componentStack),
  onCaughtError: (error, info) => report(error, info.componentStack),
}).render(<App />);

Это удобная точка, чтобы отправлять все ошибки рендера в одно место, а не дописывать componentDidCatch в каждую границу. Сами границы всё равно нужны: обработчики только сообщают об ошибке, запасной интерфейс рисует граница.

Как отправлять ошибки Error Boundary в мониторинг

console.error в componentDidCatch видят только те, у кого открыты DevTools, — то есть не посетители. Чтобы узнавать об ошибках, которые случаются у людей, их нужно отправлять в систему мониторинга вместе со стеком компонентов.

В пакете @nablops/react есть готовая граница nabl.ErrorBoundary. Она ловит ошибку рендера, отправляет её в NablOps со стеком компонентов и показывает fallback:

tsx
import * as nabl from '@nablops/react';

nabl.init({ key: 'pk_…' });

createRoot(document.getElementById('root')!, {
  onUncaughtError: nabl.reactErrorHandler(),
  onCaughtError: nabl.reactErrorHandler(),
}).render(
  <nabl.ErrorBoundary fallback={({ resetError }) => <ErrorScreen onRetry={resetError} />} tags={{ area: 'app' }}>
    <App />
  </nabl.ErrorBoundary>,
);
  • fallback — элемент или функция, которая получает error, componentStack и resetError(). Без fallback на месте упавшего дерева ничего не рисуется.
  • onError(error, componentStack) вызывается после отправки, onReset — при resetError().
  • tags — теги события, по ним удобно отличать ошибки разных частей приложения.
  • nabl.reactErrorHandler() подходит для onUncaughtError, onCaughtError и onRecoverableError в React 19. Ошибка, которую уже отправила граница, второй раз из onCaughtError или window.onerror не уходит.

Ошибки из обработчиков событий и асинхронного кода, до которых граница не дотягивается, пакет ловит сам — через window.onerror и отклонённые промисы. Если такую ошибку вы поймали и обработали, но знать о ней хотите, отправьте её вручную: nabl.captureException(err).

Уже используете react-error-boundary? Оставьте его и отправляйте ошибку из onError:

tsx
<ErrorBoundary
  FallbackComponent={Fallback}
  onError={(error, info) => nabl.captureException(error, { componentStack: info.componentStack ?? undefined })}
>

Где в ваших компонентах упала ошибка

В NablOps ошибка фронтенда появляется на вкладке «Ошибки» с пометкой «ошибка рендера React». На её странице есть блок «Компоненты React» — цепочка компонентов до упавшего, а также браузеры, системы, страницы и затронутые сессии.

В продакшене код минифицирован, и стек без карт выглядит как at Xo (index-B3x.js:1:48213). Если сборка загружает source maps (@nablops/vite-plugin для Vite или @nablops/cli для других сборщиков), в стеке видны ваш файл, функция, строка и код вокруг неё, а для упавшего компонента — где в ваших компонентах это случилось. Карты на сайт не выкладываются: посетители их не видят.

Разобрать ошибку можно и через ИИ-ассистента: он видит стек, компоненты и сессию, в которой ошибка случилась.

Что дальше

Попробуйте NablOps

Первый сервер или стек подключается за пару минут. Бесплатно в раннем доступе.

Создать аккаунт

Нашли неточность или не хватает ответа? Напишите в поддержку