Границы ошибок и доступа: 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 |
| Ошибка в корневом layout | global-error.tsx | 500 |
| Ошибка одного виджета на странице | catchError(Fallback) | Страница работает |
| Сущности нет | notFound() → not-found.tsx | 404 |
| Пользователь не вошёл | unauthorized() → unauthorized.tsx | 401 |
| Вошёл, но нет прав | forbidden() → forbidden.tsx | 403 |
| Ошибка ввода в форме | return { errors } из Action | 200 |
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