Як виправити внутрішню помилку 500 у серверних компонентах Next.js

Ви відкриваєте маршрут у проєкті Next.js з App Router, сторінка працювала лише мить тому, а тепер браузер показує «Внутрішню помилку сервера» або відповідь HTTP 500. Оновлення сторінки не допомагає. Консоль на стороні клієнта може містити мало корисної інформації, оскільки збій стався під час рендерингу серверного компонента на сервері.

Така ситуація досить поширена, щоб здаватися загадковою, але помилка 500 — це не діагноз. Вона означає, що сервер зіткнувся з неочікуваною умовою під час обробки запиту. Next.js може повернути помилку 500 через необроблену помилку додатка, і серверні компоненти особливо важливо перевіряти, оскільки вони можуть виконувати доступ до даних, запити до бази даних, перевірки автентифікації та іншу логіку, доступну лише на сервері, під час рендерингу.

Примітка щодо версії: станом на 11 вересня 2026 року офіційна документація Next.js вказує версію Next.js 16.3.4 як останню. Формулювання помилок, оверлеї розробки, поведінка середовища виконання та логи розгортання можуть відрізнятися залежно від версії та хостинг-платформи, тому використовуйте трасування стека з вашого власного проєкту як основне джерело доказів.

Що зазвичай спричиняє помилку 500 у серверному компоненті?

У App Router Next.js використовує серверні компоненти за замовчуванням. Офіційна документація про серверні та клієнтські компоненти пояснює, що серверні компоненти виконуються на сервері та можуть виконувати серверну роботу, таку як доступ до даних. Якщо одна з цих операцій генерує виняток, і цей виняток не оброблений так, щоб створити валідну відповідь або резервний варіант, запит може завершитися невдало.

Крок 1: Відтворіть збій маршруту локально та прочитайте вивід сервера

Почніть з найлегше доступних доказів. Запустіть той самий проєкт локально за допомогою вашої звичайної команди розробки, наприклад npm run dev, і запитайте саме той маршрут, який не працює. Не починайте зі зміни кешування, оновлення пакетів або видалення файлів блокування. Спершу знайдіть перший значущий виняток у терміналі, де працює Next.js.

Браузер повідомляє вам, що запит не вдався; трасування стека сервера з більшою ймовірністю пояснить чому. Шукайте перший рядок у коді вашого власного додатка, а не останній рядок у внутрішніх механізмах фреймворку. Запишіть маршрут, файл, номер рядка, тип помилки та чи виникає збій під час кожного запиту, чи лише зі специфічними даними.

Якщо проблема виникає лише в продакшені, використовуйте логи середовища виконання вашого хостингу. На Vercel офіційне керівництво з логування розрізняє логи збірки та логи середовища виконання та пояснює, що записи середовища виконання можна фільтрувати за кодом статусу та шляхом запиту. Vercel також документує, що збій виклику функції може повернути помилку 500, коли середовище виконання аварійно завершує роботу або виникає необроблений виняток або відмова промісу.

Крок 2: Ізольте отримання даних і зробіть збої явними

Серверні компоненти часто зазнають збоїв, очікуючи відповіді від віддаленого API або бази даних. Офіційний навчальний посібник Next.js з отримання даних демонструє, як серверні компоненти виконують асинхронний доступ до даних на стороні сервера. Розглядайте кожну зовнішню залежність як потенційну точку збою.

Для fetch() розрізняйте збій мережі та помилку відповіді HTTP. Відповідь із неуспішним статусом слід перевіряти перед аналізом або рендерингом її даних. Невелика обгортка робить справжню проблему видимою в логах сервера:

async function getData() {
  const apiUrl = process.env.API_URL;

  if (!apiUrl) {
    throw new Error('API_URL is not configured');
  }

  const response = await fetch(apiUrl, { cache: 'no-store' });

  if (!response.ok) {
    throw new Error(`Upstream request failed: ${response.status}`);
  }

  return response.json();
}

Не записуйте в логи токени доступу, куки, заголовки авторизації, паролі до бази даних або повні URL-адреси з секретами. Коду статусу, назви цілі запиту, ідентифікатора кореляції та очищеного повідомлення про помилку зазвичай достатньо, щоб ідентифікувати залежність, що не працює.

Крок 3: Перевірте змінні середовища та межу сервера/клієнта

Якщо той самий коміт працює локально, але повертає помилку 500 після розгортання, порівняйте середовища перед зміною логіки додатка. Переконайтеся, що кожна необхідна серверна змінна існує в цільовому середовищі розгортання і що її значення вказує на сервіс, доступний з цього середовища виконання. Локальний файл .env не доводить, що розгортання в продакшені має ті самі значення.

Потім перевірте межі компонентів. Серверні компоненти Next.js є стандартними в App Router, тоді як інтерактивний код, який потребує стану, ефектів, обробки подій або API, доступних лише в браузері, належить до клієнтського компонента. Офіційні навчальні матеріали Next.js демонструють переміщення компонента, що використовує useState, за директиву 'use client'. Деякі помилки меж виявляються під час компіляції, а не перетворюються на помилку 500, але їх виключення запобігає помилковому трактуванню помилки структури коду як збою хостингу.

Також перевірте будь-який пакет, призначений лише для сервера, який передбачає певну можливість Node.js, структуру файлової системи, нативний бінарний файл або мережеве середовище. Залежність може працювати на одній машині та зазнавати збоїв в іншому середовищі виконання, якщо ці передумови відрізняються.

Крок 4: Додайте правильну обробку помилок замість приховування винятку

Коли кореневу причину відомо, вирішіть, чи є помилка очікуваною, чи неочікуваною. Відсутній запис може потребувати відповіді «не знайдено». Помилка валідації може потребувати звичайного повідомлення. Неочікуваний виняток слід записати в лог і дозволити йому досягти межі помилок, замість того щоб мовчки перетворювати його на порожні дані, які зламають щось інше.

Next.js документує спеціальний файл error.tsx як межу помилок сегмента маршруту для неочікуваних помилок. Його компонент є клієнтським компонентом і може запропонувати повторну спробу через надану функцію reset. Офіційний посібник Next.js з обробки помилок також демонструє використання notFound(), коли запитаний ресурс не існує.

'use client';

export default function Error({
  reset,
}: {
  reset: () => void;
}) {
  return (
    <main>
      <h2>Something went wrong.</h2>
      <button onClick={() => reset()}>Try again</button>
    </main>
  );
}

Межа помилок покращує те, що бачить користувач; вона не виправляє базовий виняток. Зберігайте лог на стороні сервера, який ідентифікує причину, і не розкривайте чутливі трасування стека або секрети в інтерфейсі користувача.

Крок 5: Перевірте виправлення у збірці, наближеній до продакшену

Сервер розробки необхідний для діагностики, але це не фінальний тест. Після того, як маршрут працює локально, запустіть збірку для продакшену за допомогою менеджера пакетів вашого проєкту, запустіть її в режимі продакшену, коли це практично, і запитайте той самий маршрут з тими самими релевантними умовами даних. Потім перевірте розгорнуте середовище з відкритими логами середовища виконання.

npm run build
npm start

Якщо ваша платформа хостингу виконує збірку інакше, ніж ваш ноутбук, також протестуйте попереднє розгортання перед впровадженням зміни. Виправлення є достовірним лише тоді, коли маршрут повертає очікуваний статус, рендерить очікуваний вміст і для цього запиту не з'являється новий виняток на сервері.

Як переконатися, що помилку 500 дійсно виправлено

• Раніше проблемний URL завантажується повторно без відповіді HTTP 500.
• Термінал сервера або логи середовища виконання в продакшені більше не показують початковий виняток.
• Те саме виправлення витримує npm run build та запуск у режимі продакшену або попереднє розгортання.
• Необхідні змінні середовища присутні в середовищі, де спочатку стався збій.
• Збої зовнішнього API або бази даних тепер створюють контрольований шлях обробки помилок замість незрозумілого аварійного завершення роботи.
• Інтерактивний код, доступний лише в браузері, знаходиться в клієнтських компонентах, тоді як секрети та привілейований доступ до даних залишаються на сервері.
• Межа error.tsx надає користувачам розумний резервний варіант для неочікуваних збоїв сегмента маршруту.

Якщо проблема залишається

Спрощуйте маршрут, доки збій не зникне. Тимчасово замініть одну залежність за раз на відоме безпечне значення: спочатку виклик бази даних, потім зовнішній API, потім автентифікацію або пошук сесії, потім дочірні компоненти. Перша видалена операція, яка змушує помилку 500 зникнути, вказує на область для розслідування. Відновіть кожну залежність після тестування, замість того щоб залишати фейкові дані у фінальному додатку.

Для проблем, що виникають лише в продакшені, порівняйте точний розгорнутий коміт, конфігурацію Node/середовища виконання, змінні середовища, мережеву доступність та версії залежностей. Якщо платформа повідомляє про код помилки, специфічний для провайдера, використовуйте офіційну документацію провайдера для цього точного коду, замість того щоб припускати, що кожна помилка 500 має ту саму причину.

Головне правило усунення несправностей просте: розглядайте «Внутрішню помилку 500» як симптом. Корисним доказом є виняток на стороні сервера, який стався безпосередньо перед нею. Спершу знайдіть цей виняток, зробіть залежність, що не працює, явною, виправте середовище або межу коду, яка його спричинила, і перевірте результат у тому самому середовищі виконання, де виникла проблема.