Иерархия error.tsx: что на самом деле ловит каждая граница, digest и когда reset() врёт

Граница оборачивает page, а не собственную раму

Ловушка размещения существует из-за того, как Next.js собирает файловые конвенции сегмента в одно React-дерево. Для каждого сегмента error.tsx становится React-границей ошибок, вложенной внутрь layout этого же сегмента:

// Что Next.js концептуально собирает из файлов одного сегмента
<Layout>                                {/* layout.tsx — СНАРУЖИ границы */}
  <ErrorBoundary fallback={<Error />}>  {/* error.tsx рендерит фолбэк */}
    <Page />                            {/* page.tsx + все вложенные сегменты */}
  </ErrorBoundary>
</Layout>

Поэтому checkout/error.tsx ловит всё, что брошено при рендере checkout/page.tsx и любого сегмента ниже, — но ошибка, брошенная самим checkout/layout.tsx, возникает в дереве выше границы и всплывает вверх, пока не встретит error.tsx родительского сегмента. Правило для запоминания: чтобы прикрыть layout, граница должна жить уровнем выше. Если выше по дереву её никто не ловит, падение доходит до корневого layout, и остаётся только global-error.tsx. Этот файл особенный трижды: в активном состоянии он заменяет весь корневой layout, поэтому обязан сам рендерить теги html и body; он обязан быть клиентским компонентом; и в разработке вы его почти не увидите, потому что ошибки перехватывает dev-оверлей, — это фактически поведение «только в продакшене», а значит проверять его надо на продакшен-сборке, а не в next dev.

Ещё одно роутинговое различие, которое по ошибке записывают в обработку ошибок: notFound() бросает специальную control-flow-ошибку, которую рендерит ближайший not-found.tsx, — error.tsx её не видит, как не видит и throw внутри redirect(). Границы ошибок — для сбоев, not-found — это семантика маршрутизации. Catch-all, сливающий отсутствующие сущности в границу ошибок, превращает корректный 404 в фальшивый 500 — неверный статус-код, неверное кеширование, неверная страница в поисковом индексе.

reset() повторяет рендер — он не чинит мир

error.tsx получает { error, reset }. Вызов reset() перерендеривает содержимое границы — и именно это различие решает, честна ли ваша кнопка «Повторить». При временном сбое — сетевой моргнул, зависимость посреди деплоя, апстрим отвалился по таймауту — повтор действительно восстанавливает. При детерминированной ошибке — баг парсинга, null-поле в базе, сломанный флаг из пролога — reset() мгновенно бросает снова, и автоповторяющая граница превращается в плотный цикл, долбящий сломанную зависимость. Есть и тонкость с серверными компонентами: упавшая разметка пришла из серверного рендера, поэтому повторный рендер только на клиенте проигрывает тот же сломанный payload. Рабочий паттерн объединяет reset() с router.refresh() внутри transition и ограничивает попытки:

'use client'; // error.tsx — всегда клиентский компонент
import { useRouter } from 'next/navigation';
import { startTransition, useState } from 'react';

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  const router = useRouter();
  const [attempts, setAttempts] = useState(0);

  const retry = () => {
    setAttempts((n) => n + 1);
    startTransition(() => {
      router.refresh(); // заново запросить payload серверных компонентов
      reset();          // затем перерендерить детей границы
    });
  };

  return (
    <div role="alert">
      <p>Чекаут временно недоступен. Код обращения: {error.digest}</p>
      {attempts < 2
        ? <button onClick={retry}>Повторить</button>
        : <a href="/support">Написать в поддержку</a>}
    </div>
  );
}

Этот error.digest — продакшен-контракт (digest — хеш-отпечаток исходной серверной ошибки, одинаковый на сервере и в браузере). Когда серверный компонент бросает ошибку в продакшене, Next.js срезает message и stack до того, как что-либо уйдёт по проводу, — поэтому брошенный Error("duplicate key on users.email: alice@…") не утечёт схемой, SQL или PII в браузер. Клиент получает общий текст плюс digest: хеш, который Next.js также прикрепляет к серверному логу исходной ошибки. На этом хеше держится весь процесс поддержки — выводите digest в фолбэке, логируйте его на сервере, и скриншот пользователя превращается в поиск одним grep. Ошибки клиентских компонентов не редактируются: они уже исполнились в браузере. Отсюда два режима отказа: команда, прячущая digest от пользователей, вообще не имеет пути корреляции, а команда, льющая логи в эфемерный stdout с суточным удержанием, держит digest, указывающий на удалённые улики.

Проектирование яруса: границы по радиусу поражения

Разобравшись, где границы сидят в дереве, стоит задать следующий вопрос: сколько их рисовать — ошибиться здесь тише, чем пропустить границу, но не менее разрушительно. Не каждый сегмент заслуживает свой error.tsx. Каждый — это небольшой кусок клиентского бандла (граница — клиентский компонент: примерно 1–2 КБ плюс импортируемый ею UI) и, что важнее, решение об изоляции. Рабочая эвристика: рисуйте границу там, где остаток страницы всё ещё стоит показывать. Дашборду с четырьмя независимыми группами виджетов нужна граница на группу — упавшая панель аналитики не должна убивать навигацию и три остальные панели. Воронке чекаута нужна одна граница в корне воронки, чей фолбэк сохраняет контекст корзины. Маркетинговые страницы могут ехать на одном app/error.tsx. И ярус всегда завершают два файла: app/error.tsx, ловящий всё ниже корневого layout, и брендированный global-error.tsx как последний рубеж над ним.

Режим отказа от пере-ярусирования тише: когда умирает что-то системное — хранилище сессий, пул базы — четырнадцать виджетных границ рендерят четырнадцать вежливых грустных смайликов, и страница выглядит «деградировавшей, но живой», хотя не работает ничего. Системные сбои должны доходить до высокой границы, рассказывающей одну честную историю. Последний механический факт, унаследованный от самого React: границы ловят ошибки, брошенные во время рендера (серверного или клиентского) и в lifecycle, — но не внутри обработчиков событий и оторванного асинхронного кода. onClick, у которого упал fetch, никогда не активирует error.tsx — ему нужны собственный try/catch и состояние UI.