re:re:actable
Урок 094 минуты чтения

Границы ошибок и доступа: catchError, forbidden и unauthorized

На этой странице
Кратко

В App Router у каждого вида «неуспеха» есть свой инструмент. error.tsx — граница непредвиденных ошибок сегмента, с Next 16.3 получает retry(), который перезапрашивает и перерисовывает серверные компоненты (старый reset() только сбрасывает клиентское состояние). global-error.tsx — ошибки корневого layout. catchError из next/error (16.3) — своя граница ошибок для части страницы (виджета), которая не мешает notFound()/redirect() и тоже умеет retry(). notFound() + not-found.tsx — 404. unauthorized() + unauthorized.tsx — 401 (не вошёл), forbidden() + forbidden.tsx — 403 (нет прав); оба включаются флагом authInterrupts. Ожидаемые ошибки (валидация формы) возвращаются данными из Server Action, а не исключениями.

Вопрос

Как в Next.js правильно разделять ошибки: непредвиденный сбой, «не найдено», «не авторизован», «нет прав», ошибка части страницы?

Карта

СитуацияИнструментСтатус
Непредвиденная ошибка в сегментеerror.tsx (retry, reset)500
Ошибка в корневом layoutglobal-error.tsx500
Ошибка одного виджета на страницеcatchError(Fallback)Страница работает
Сущности нетnotFound() → not-found.tsx404
Пользователь не вошёлunauthorized() → unauthorized.tsx401
Вошёл, но нет правforbidden() → forbidden.tsx403
Ошибка ввода в формеreturn { errors } из Action200

error.tsx с retry

// app/dashboard/error.tsx
'use client';
 
import { useEffect } from 'react';
 
export default function DashboardError({ error, retry }: { error: unknown; retry: () => void }) {
  useEffect(() => {
    reportError(error); // в production message серверной ошибки скрыт, есть digest для логов
  }, [error]);
 
  return (
    <section role="alert">
      <h2>Не удалось загрузить панель</h2>
      <button onClick={() => retry()}>Попробовать снова</button>
    </section>
  );
}

error.tsx оборачивает page, loading, not-found и вложенные layout сегмента, но не layout того же уровня — для него нужна граница уровнем выше или global-error.tsx.

catchError: граница для части страницы

// components/widget-boundary.tsx
'use client';
 
import { catchError, type ErrorInfo } from 'next/error';
 
function WidgetFallback({ title }: { title: string }, { error, retry }: ErrorInfo) {
  return (
    <div role="alert" className="widget-error">
      <p>{title}: не удалось загрузить</p>
      <button onClick={() => retry()}>Повторить</button>
    </div>
  );
}
 
export default catchError(WidgetFallback);
// app/dashboard/page.tsx
import WidgetBoundary from '@/components/widget-boundary';
 
export default function Dashboard() {
  return (
    <>
      <Summary />
      <WidgetBoundary title="Продажи">
        <SalesChart /> {/* упадёт — остальная страница продолжит работать */}
      </WidgetBoundary>
      <WidgetBoundary title="Отзывы">
        <LatestReviews />
      </WidgetBoundary>
    </>
  );
}

Почему не обычный React Error Boundary: самописная граница перехватывала бы и служебные «ошибки» notFound()/redirect(), ломая их, и не умела бы перезапросить серверные компоненты.

unauthorized и forbidden

// next.config.ts
const nextConfig: NextConfig = {
  experimental: { authInterrupts: true },
};
// app/admin/page.tsx
import { unauthorized, forbidden } from 'next/navigation';
import { getCurrentUser } from '@/lib/dal';
 
export default async function AdminPage() {
  const user = await getCurrentUser();
  if (!user) unauthorized();                 // 401 → app/unauthorized.tsx
  if (!user.roles.includes('admin')) forbidden(); // 403 → app/forbidden.tsx
  return <AdminPanel />;
}
// app/unauthorized.tsx
import Link from 'next/link';
 
export default function Unauthorized() {
  return (
    <main>
      <h1>Нужно войти</h1>
      <Link href="/login">Войти</Link>
    </main>
  );
}

Работают в серверных компонентах, Server Actions и Route Handlers. До этих API приходилось либо редиректить на /login (теряя правильный статус), либо рисовать «Нет доступа» со статусом 200.

Ожидаемые ошибки — как данные

'use server';
export async function updateProfile(_prev: State, formData: FormData): Promise<State> {
  const parsed = Schema.safeParse(Object.fromEntries(formData));
  if (!parsed.success) return { errors: parsed.error.flatten().fieldErrors }; // не throw
  // ...
}

Исключение из Action переведёт пользователя на экран ошибки — для «email занят» это плохой UX.

Что важно помнить

  • Сообщения серверных ошибок в production не уходят в браузер — смотри логи по error.digest.
  • notFound, redirect, unauthorized, forbidden работают через исключения: не ловить их в try/catch (или пробрасывать через unstable_rethrow).
  • Статус-коды при стриминге: если граница сработала после начала ответа, статус уже не изменить.

Мини-шпаргалка

error.tsx → retry() (16.3+) / reset(); не ловит layout своего уровня
global-error.tsx → корневой layout, свои <html>/<body>
catchError(Fallback) из next/error → граница виджета, retry()
notFound → 404 · unauthorized → 401 · forbidden → 403 (experimental.authInterrupts)
Валидация → return { errors }, не throw

Документация

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам