Обработка ошибок

Если при отрисовке страницы выброшено исключение — база данных недоступна, внешний API ответил ошибкой, — Next.js по умолчанию покажет пустую страницу с сообщением о сбое. Файл error.tsx позволяет заменить её своей страницей с понятным текстом и кнопкой «Попробовать снова».

Файл error.tsx

Создайте app/posts/error.tsx. Он обязательно клиентский — кнопка повтора работает в браузере:

// app/posts/error.tsx
'use client';
 
export default function PostsError({ error, retry }: { error: Error; retry: () => void }) {
  return (
    <div>
      <h2>Не удалось загрузить статьи</h2>
      <p>{error.message}</p>
      <button onClick={() => retry()}>Попробовать снова</button>
    </div>
  );
}

Next.js передаёт компоненту объект ошибки error и функцию retry, которая заново запрашивает данные и пытается отрисовать страницу. В статьях о Next.js 15 вместо неё встречается reset: она тоже есть, но только сбрасывает ошибку без повторной загрузки данных.

Проверка

Временно выбросьте ошибку в getPosts из lib/posts.ts:

// lib/posts.ts (временно)
export async function getPosts(): Promise<Post[]> {
  throw new Error('База данных недоступна');
}

Откройте /posts: вместо списка появится «Не удалось загрузить статьи», а шапка и меню из макетов останутся на месте. Верните код функции обратно.

Где срабатывает error.tsx

Файл ловит ошибки страниц своей папки и всех вложенных — /posts, /posts/hello-nextjs. Макет той же папки он не ловит: ошибку в app/posts/layout.tsx обработает error.tsx уровнем выше. Ошибки корневого макета ловит отдельный файл app/global-error.tsx; он заменяет всю страницу, поэтому сам содержит теги html и body.

Сообщение в продакшене

В собранной версии сайта текст ошибок из серверных компонентов скрыт: error.message содержит общую фразу, а у объекта есть поле digest — код, по которому ошибку можно найти в логах сервера. Так посетитель не увидит внутренние подробности вроде пути к базе.

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

Не каждая ошибка — исключение. Неверно заполненная форма или занятый адрес статьи — ожидаемые ситуации. В серверных действиях такие ошибки возвращают значением, как в уроке о проверке формы, и показывают рядом с полем. error.tsx оставляют для настоящих сбоев.

Частая ошибка

Забыть 'use client' в первой строке error.tsx. Next.js сразу сообщит, что файл ошибки должен быть клиентским компонентом. Помните: error.tsx и global-error.tsx — всегда клиентские, а not-found.tsx и loading.tsx могут быть серверными.