Обробка помилок у Next.js

Next.js App Router використовує файлову систему для обробки помилок. Файли error.tsx та not-found.tsx автоматично створюють межі помилок на кожному рівні сегмента маршруту.

error.tsx

Файл error.tsx ловить помилки під час виконання та показує резервний інтерфейс замість зламаної сторінки:

tsx

'use client'

export default function Error({
  error,
  reset
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <div>
      <h2>Щось пішло не так</h2>
      <p>{error.message}</p>
      <button onClick={() => reset()}>Спробувати ще раз</button>
    </div>
  )
}

Ключові моменти:

error.tsx має бути клієнтським компонентом ('use client')
reset намагається повторно відрендерити сегмент
error.digest містить хеш помилки для серверного журналювання

Вкладена обробка помилок

Помилки піднімаються до найближчого error.tsx:

app
error.tsx
problems
error.tsx
page.tsx
[id]
page.tsx

Помилка в /problems/123 буде перехоплена app/problems/error.tsx. Якщо його не існує, вона підніметься до app/error.tsx.

Важливо:

error.tsx не перехоплює помилки в layout.tsx того ж сегмента, оскільки межа помилки вкладена всередині макета. Щоб обробити помилки макета, вам потрібно мати error.tsx у батьківському сегменті.

global-error.tsx

Для обробки помилок у кореневому макеті:

tsx

// app/global-error.tsx
'use client'

export default function GlobalError({
  error,
  reset
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <html>
      <body>
        <h2>Сталася критична помилка</h2>
        <button onClick={() => reset()}>Перезавантажити</button>
      </body>
    </html>
  )
}

global-error.tsx замінює весь кореневий макет, тому він повинен містити <html> та <body>.

not-found.tsx

Для обробки помилок 404:

tsx

// app/not-found.tsx
import Link from 'next/link'

export default function NotFound() {
  return (
    <div>
      <h2>Сторінку не знайдено</h2>
      <p>Ми не змогли знайти запитувану сторінку на IT Lead.</p>
      <Link href="/">Повернутися на головну сторінку</Link>
    </div>
  )
}

not-found.tsx автоматично спрацьовує, коли Next.js не може знайти маршрут. Його також можна викликати вручну:

tsx

import { notFound } from 'next/navigation'

export default async function DocPage({
  params
}: {
  params: { slug: string }
}) {
  const doc = await getDoc(params.slug)

  if (!doc) {
    notFound()
  }

  return <article>{doc.content}</article>
}

Порядок обробки

layout.tsx
  error.tsx ← ловить помилки з:
    loading.tsx
      not-found.tsx
        page.tsx ← помилки тут піднімаються до error.tsx

Обробка помилок у серверних діях

Серверні дії повертають помилки через return, а не throw:

tsx

'use server'

export async function updateProfile(formData: FormData) {
  try {
    await db.user.update({ ... })
    revalidatePath('/settings')
    return { success: true }
  } catch (error) {
    return { error: 'Не вдалося оновити профіль' }
  }
}

Корисні ресурси

nextjs.org/docs — Обробка помилок
API Reference для error.tsx

Суміжні теми

Коротка відповідь

Для співбесіди

Premium

Коротка відповідь допоможе вам впевнено відповідати на цю тему під час співбесіди.

Дочитали статтю?

Практика завдань