Ako opraviť internú chybu 500 v Next.js Server Components

Otvoríte trasu v projekte Next.js App Router, stránka pred chvíľou fungovala a teraz prehliadač zobrazuje Internú chybu servera alebo odpoveď HTTP 500. Obnovenie nepomáha. Konzola na strane klienta môže zobrazovať len málo užitočných informácií, pretože k zlyhaniu došlo počas vykresľovania Server Component na serveri.

Táto situácia je natoľko bežná, že pôsobí záhadne, ale chyba 500 nie je diagnóza. Znamená to, že server narazil na neočakávanú podmienku pri spracovaní požiadavky. Next.js môže vrátiť chybu 500 pri neošetrených aplikáciách a Server Components je obzvlášť dôležité skontrolovať, pretože počas vykresľovania môžu vykonávať prístup k dátam, databázové dotazy, overovanie autentifikácie a ďalšiu logiku dostupnú iba na serveri.

Poznámka k verzii: podľa overenia z 11. septembra 2026 oficiálna dokumentácia Next.js uvádza Next.js 16.3.4 ako najnovšiu verziu. Formulácia chýb, vývojové prekrytia, správanie runtime a logy nasadenia sa môžu líšiť podľa verzie a hostingovej platformy, preto ako primárny dôkaz použite stack trace z vášho vlastného projektu.

Čo zvyčajne spôsobuje chybu 500 v Server Component?

V App Router používa Next.js štandardne Server Components. Oficiálna dokumentácia Server and Client Components vysvetľuje, že Server Components sa vykonávajú na serveri a môžu vykonávať server-side úlohy, ako je prístup k dátam. Ak jedna z týchto operácií vyhodí výnimku a táto výnimka nie je ošetrená spôsobom, ktorý vytvorí platnú odpoveď alebo fallback, požiadavka môže zlyhať.

Pravdepodobná príčina	Na čo sa zamerať	Prvý krok
Zlyhanie požiadavky na API	Chyby DNS, zlyhania pripojenia, neočakávané odpovede 401/403/404/500, neplatný JSON	Zaznamenajte stav upstream a skontrolujte response.ok
Zlyhanie databázy	Chyby pripojenia, chýbajúca tabuľka, expirované prihlasovacie údaje, výnimky v dotazoch	Spustite dotaz samostatne a skontrolujte serverové logy
Chýbajúca premenná prostredia	undefined URL, token, reťazec pripojenia alebo tajný kľúč	Overte lokálne a nasadené nastavenia prostredia samostatne
Problém s hranicou server/klient	Hák, API prehliadača alebo interaktívny kód použitý v nesprávnej komponente	Presuňte interaktívny kód za hranicu 'use client'
Neošetrená výnimka aplikácie	Stack trace ukazuje na vašu stránku, layout, pomocnú funkciu, kód autentifikácie alebo knižnicu	Opravte riadok vyhadzujúci výnimku a potom pridajte vhodnú hranicu chýb
Problém s nasadením/runtime	Funguje lokálne, ale zlyháva až po nasadení	Porovnajte premenné runtime, prístup k sieti, predpoklady Node/runtime a produkčné logy

Krok 1: Reprodukovanie zlyhávajúcej trasy lokálne a čítanie výstupu servera

>Začnite najjednoduchším dôkazom, ktorý môžete získať. Spustite rovnaký projekt lokálne pomocou bežného príkazu pre vývoj, napríklad npm run dev, a požiadajte o presnú trasu, ktorá zlyháva. Nezačínajte zmenou cache, aktualizáciou balíčkov alebo mazaním lockfileov. Najprv nájdite prvú významnú výnimku v termináli, kde beží Next.js.

Prehliadač vám povie, že požiadavka zlyhala; stack trace na serveri vám pravdepodobnejšie povie prečo. Hľadajte prvý riadok vo vašom vlastnom kóde aplikácie, nie posledný riadok vo vnútri interných častí frameworku. Zaznamenajte trasu, súbor, číslo riadku, typ chyby a či k zlyhaniu dochádza pri každej požiadavke, alebo len pri špecifických dátach.

Ak sa problém vyskytuje iba v produkcii, použite namiesto toho runtime logy vášho hostiteľa. Na Vercel oficiálna smernica o logovaní rozlišuje build logy od runtime logov a vysvetľuje, že runtime záznamy možno filtrovať podľa stavového kódu a cesty požiadavky. Vercel tiež dokumentuje, že zlyhanie vyvolania funkcie môže vrátiť chybu 500, keď runtime zlyhá alebo dôjde k nechytenéj výnimke alebo zamietnutiu.

Krok 2: Izolujte načítavanie dát a urobte zlyhania explicitnými

Server Components často zlyhávajú počas čakania na upstream API alebo databázu. Oficiálny tutorial načítavania dát Next.js ukazuje Server Components vykonávajúce asynchrónny server-side prístup k dátam. Zaobchádzajte s každou externou závislosťou ako s možným bodom zlyhania.

Pre fetch() rozlišujte zlyhanie siete od chybovej odpovede HTTP. Odpoveď s neúspešným stavovým kódom by sa mala skontrolovať pred parsovaním alebo vykresľovaním jej dát. Malý obal zviditeľní skutočný problém v serverových logoch:

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();
}

Nelogujte prístupové tokeny, cookies, hlavičky autorizácie, heslá databázy ani celé URL obsahujúce tajné kľúče. Stavový kód, názov cieľa požiadavky, korelačné ID a sanitizovaná chybová správa sú zvyčajne dostatočné na identifikáciu zlyhávajúcej závislosti.

Krok 3: Skontrolujte premenné prostredia a hranicu server/klient

Ak rovnaký commit funguje lokálne, ale po nasadení vráti chybu 500, porovnajte prostredia pred zmenou logiky aplikácie. Uistite sa, že každá požadovaná serverová premenná existuje v cieľovom nasadení a že hodnota smeruje na službu dostupnú z tohto runtime. Lokálny súbor .env nedokazuje, že produkčné nasadenie má rovnaké hodnoty.

Potom skontrolujte hranice komponentov. Server Components Next.js sú v App Router predvolené, zatiaľ čo interaktívny kód, ktorý potrebuje stav, efekty, obsluhu udalostí alebo API dostupné iba v prehliadači, patrí do Client Component. Oficiálny výukový materiál Next.js demonštruje presunutie komponenty používajúcej useState za direktívu 'use client'. Niektoré chyby hraníc sú zachytené počas kompilácie namiesto toho, aby sa stali chybou 500, ale ich vylúčenie vám zabráni považovať chybu štruktúry kódu za výpadok hostingu.

Tiež skontrolujte akýkoľvek package určený iba pre server, ktorý predpokladá konkrétnu schopnosť Node.js, rozloženie súborového systému, natívny binárny súbor alebo sieťové prostredie. Závislosť môže fungovať na jednom počítači a zlyhať v inom runtime, ak sa tieto predpoklady líšia.

Krok 4: Pridajte správne spracovanie chýb namiesto skrývania výnimky

Akonáhle je známa príčina, rozhodnite, či je chyba očakávaná alebo neočakávaná. Chýbajúci záznam si môže vyžadovať odpoveď not-found. Zlyhanie validácie si môže vyžadovať bežnú správu. Neočakávaná výnimka by sa mala zaznamenať a nechať dosiahnuť hranicu chýb, namiesto tichého prevodu na prázdne dáta, ktoré niekde inde spôsobia problémy.

Next.js dokumentuje špeciálny súbor error.tsx ako hranicu chýb pre segment trasy pri neočakávaných chybách. Jeho komponenta je Client Component a môže ponúknuť opakovanie pomocou poskytnutej funkcie reset. Oficiálna príručka spracovania chýb Next.js tiež demonštruje použitie notFound(), keď požadovaný zdroj neexistuje.

'use client';

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

Hranica chýb zlepšuje to, čo vidí používateľ; neopravuje základnú výnimku. Ponechajte serverový log, ktorý identifikuje príčinu, a neexponujte citlivé stack trace alebo tajné kľúče v UI.

Krok 5: Overte opravu v produkcii podobnom buildu

Vývojový server je nevyhnutný na diagnostiku, ale nie je to konečný test. Po tom, čo trasa funguje lokálne, spustite produkčný build pomocou správcu balíčkov vášho projektu, spustite ho v produkčnom režime, ak je to praktické, a požiadajte o rovnakú trasu s rovnakými relevantnými dátovými podmienkami. Potom overte nasadené prostredie s otvorenými runtime logmi.

npm run build
npm start

Ak vaša hostingová platforma builduje inak ako váš laptop, otestujte aj preview nasadenie pred povýšením zmeny. Oprava je dôveryhodná len vtedy, keď trasa vráti očakávaný stav, vykreslí očakávaný obsah a pri danej požiadavke sa neobjaví žiadna nová serverová výnimka.

Ako potvrdiť, že chyba 500 je skutočne opravená

• Predtým zlyhávajúca URL sa načítava opakovane bez odpovede HTTP 500.
• Terminál servera alebo produkčné runtime logy už nezobrazujú pôvodnú výnimku.
• Rovnaká oprava prežije npm run build a beh v produkčnom režime alebo preview nasadenie.
• Požadované premenné prostredia sú prítomné v prostredí, kde k zlyhaniu pôvodne došlo.
• Zlyhania externého API alebo databázy teraz vedú k kontrolovanej ceste chyby namiesto nevysvetliteľného zlyhania.
• Interaktívny kód dostupný iba v prehliadači je vnútri Client Components, zatiaľ čo tajné kľúče a privilegovaný prístup k dátam zostávajú na serveri.
• Hranica error.tsx poskytuje používateľom rozumný fallback pre neočakávané zlyhania segmentu trasy.

Ak stále zlyháva

Zredukujte trasu, kým nezastaví zlyhávanie. Dočasne nahraďte jednu závislosť po druhej známou bezpečnou hodnotou: najprv databázový volanie, potom externé API, potom autentifikáciu alebo vyhľadávanie relácie, potom podradené komponenty. Prvá odstránená operácia, ktorá spôsobí zmiznutie chyby 500, identifikuje oblasť na vyšetrovanie. Po otestovaní každú závislosť obnovte, namiesto ponechania falošných dát v konečnej aplikácii.

Pre problém vyskytujúci sa iba v produkcii porovnajte presný nasadený commit, konfiguráciu Node/runtime, premenné prostredia, dostupnosť siete a verzie závislostí. Ak platforma hlási chybový kód špecifický pre poskytovateľa, použite oficiálnu dokumentáciu poskytovateľa pre tento presný kód namiesto predpokladu, že každá chyba 500 má rovnakú príčinu.

Kľúčové pravidlo riešenia problémov je jednoduché: považujte „Internú chybu 500“ za symptóm. Užitočným dôkazom je serverová výnimka, ktorá nastala bezprostredne pred ňou. Najprv nájdite túto výnimku, urobte zlyhávajúcu závislosť explicitnou, opravte prostredie alebo hranicu kódu, ktorá ju spustila, a overte výsledok v rovnakom runtime, kde sa problém vyskytol.