Jak opravit interní chybu 500 v Next.js Server Components

Otevřete trasu v projektu Next.js App Router, stránka před chvílí fungovala a nyní prohlížeč zobrazuje Interní chybu serveru nebo odpověď HTTP 500. Obnovení nepomáhá. Konzole na straně klienta může zobrazovat jen málo užitečných informací, protože k selhání došlo během vykreslování Server Component na serveru.

Tato situace je natolik běžná, že působí záhadně, ale chyba 500 není diagnózou. Znamená to, že server narazil na neočekávanou podmínku při zpracování požadavku. Next.js může vrátit chybu 500 kvůli neošetřené aplikační chybě a Server Components je obzvláště důležité kontrolovat, protože během vykreslování mohou provádět přístup k datům, dotazy do databáze, ověřování autentizace a další logiku dostupnou pouze na serveru.

Poznámka k verzi: podle ověření ze dne 11. září 2026 oficiální dokumentace Next.js uvádí Next.js 16.3.4 jako nejnovější verzi. Formulace chyb, vývojové překryvy, chování runtime a logy nasazení se mohou lišit podle verze a hostingové platformy, takže jako hlavní důkaz používejte stack trace z vašeho vlastního projektu.

Co obvykle způsobuje chybu 500 v Server Component?

V App Router používá Next.js ve výchozím nastavení Server Components. Oficiální dokumentace Server and Client Components vysvětluje, že Server Components se provádějí na serveru a mohou provádět server-side úlohy, jako je přístup k datům. Pokud jedna z těchto operací vyhodí výjimku a ta není ošetřena způsobem, který vytvoří platnou odpověď nebo fallback, požadavek může selhat.

Krok 1: Reprodukovat selhávající trasu lokálně a přečíst výstup serveru

Začněte s nejjednodušším důkazem, který lze získat. Spusťte stejný projekt lokálně pomocí běžného vývojového příkazu, například npm run dev, a požádejte o přesnou trasu, která selhává. Nezačínejte změnou cache, aktualizací balíčků nebo mazáním souborů lockfile. Nejprve najděte první smysluplnou výjimku v terminálu, kde běží Next.js.

Prohlížeč vám řekne, že požadavek selhal; stack trace na serveru vám s větší pravděpodobností řekne proč. Hledejte první řádek ve vašem vlastním aplikačním kódu, nikoliv poslední řádek uvnitř interních částí frameworku. Zaznamenejte trasu, soubor, číslo řádku, typ chyby a zda k selhání dochází při každém požadavku, nebo pouze s určitými daty.

Pokud k problému dochází pouze v produkčním prostředí, použijte runtime logy vašeho hostitele. Na Vercel oficiální průvodce logováním rozlišuje build logy od runtime logů a vysvětluje, že runtime záznamy lze filtrovat podle stavového kódu a cesty požadavku. Vercel také dokumentuje, že selhání vyvolání funkce může vrátit chybu 500, pokud dojde k pádu runtime nebo k neošetřené výjimce či zamítnutí.

Krok 2: Izolovat načítání dat a explicitně ošetřit selhání

Server Components často selhávají při čekání na upstream API nebo databázi. Oficiální tutorial načítání dat v Next.js ukazuje Server Components provádějící asynchronní přístup k datům na straně serveru. Považujte každou externí závislost za možný bod selhání.

U fetch() rozlišujte mezi selháním sítě a chybovou odpovědí HTTP. Odpověď s nestavovým kódem úspěchu by měla být zkontrolována před parsováním nebo vykreslováním jejích dat. Malý wrapper učiní skutečný problém viditelným v serverových logách:

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 přístupové tokeny, cookies, hlavičky autorizace, hesla k databázi ani celé URL obsahující tajné klíče. Stavový kód, název cíle požadavku, korelační ID a vyčištěná chybová zpráva jsou obvykle dostatečné k identifikaci selhávající závislosti.

Krok 3: Zkontrolovat proměnné prostředí a hranici server/klient

Pokud stejný commit funguje lokálně, ale po nasazení vrací chybu 500, porovnejte prostředí před změnou aplikační logiky. Potvrďte, že každá požadovaná serverová proměnná existuje v cíli nasazení a že její hodnota ukazuje na službu dostupnou z tohoto runtime. Lokální soubor .env nedokazuje, že produkční nasazení má stejné hodnoty.

Poté zkontrolujte hranice komponent. Next.js Server Components jsou ve výchozím nastavení v App Router, zatímco interaktivní kód, který potřebuje stav, efekty, zpracování událostí nebo API dostupná pouze v prohlížeči, patří do Client Component. Oficiální výukový materiál Next.js demonstruje přesunutí komponenty používající useState za direktivu 'use client'. Některé chyby hranic jsou zachyceny během kompilace, nikoliv jako chyba 500, ale jejich vyloučení vám zabrání v tom, abyste chybu ve struktuře kódu považovali za výpadek hostingu.

Zkontrolujte také jakýkoli server-only balíček, který předpokládá specifickou schopnost Node.js, strukturu souborového systému, nativní binárku nebo síťové prostředí. Závislost může fungovat na jednom stroji a selhat v jiném runtime, pokud se tyto předpoklady liší.

Krok 4: Přidat správné zpracování chyb místo skrývání výjimky

Jakmile je známá příčina, rozhodněte, zda je chyba očekávaná, nebo neočekávaná. Chybějící záznam si může zasloužit odpověď not-found. Selhání validace si může zasloužit běžnou zprávu. Neočekávaná výjimka by měla být zalogována a umožněno jí dosáhnout chybové hranice, nikoliv být tiše převedena na prázdná data, která způsobí problém jinde.

Next.js dokumentuje speciální soubor error.tsx jako chybovou hranici segmentu trasy pro neočekávané chyby. Jeho komponenta je Client Component a může nabídnout opakování prostřednictvím dodané funkce reset. Oficiální průvodce zpracováním chyb v Next.js také demonstruje použití notFound(), pokud 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>
  );
}

Chybová hranice zlepšuje to, co vidí uživatel; neopravuje však základní výjimku. Ponechte serverový log, který identifikuje příčinu, a nevytvářejte citlivé stack trace ani tajné klíče v UI.

Krok 5: Ověřit opravu v buildu podobném produkci

Vývojový server je nutný pro diagnostiku, ale není konečným testem. Poté, co trasa funguje lokálně, spusťte produkční build pomocí správce balíčků vašeho projektu, spusťte jej v produkčním režimu, pokud je to praktické, a požádejte o stejnou trasu se stejnými relevantními datovými podmínkami. Poté ověřte nasazené prostředí s otevřenými runtime logy.

npm run build
npm start

Pokud vaše hostingová platforma provádí build jinak než váš laptop, otestujte také preview nasazení před povýšením změny. Oprava je důvěryhodná pouze tehdy, když trasa vrátí očekávaný stav, vykreslí očekávaný obsah a pro tento požadavek se neobjeví žádná nová serverová výjimka.

Jak potvrdit, že chyba 500 je skutečně opravena

• Předtím selhávající URL se opakovaně načítá bez odpovědi HTTP 500.
• Terminál serveru nebo produkční runtime logy již nezobrazují původní výjimku.
• Stejná oprava přežije npm run build a spuštění v produkčním režimu nebo preview nasazení.
• Požadované proměnné prostředí jsou přítomny v prostředí, kde k selhání původně došlo.
• Selhání externího API nebo databáze nyní vytvářejí kontrolovanou chybovou cestu místo nevysvětlitelného pádu.
• Interaktivní kód dostupný pouze v prohlížeči je uvnitř Client Components, zatímco tajné klíče a privilegovaný přístup k datům zůstávají na serveru.
• Chybová hranice error.tsx poskytuje uživatelům rozumný fallback pro neočekávané selhání segmentu trasy.

Pokud stále selhává

Redukujte trasu, dokud přestane selhávat. Dočasně nahraďte jednu závislost po druhé známou bezpečnou hodnotou: nejprve volání databáze, pak externí API, pak autentizaci nebo vyhledávání relace, pak podřízené komponenty. První odstraněná operace, která způsobí zmizení chyby 500, identifikuje oblast k prošetření. Po testování každou závislost obnovte, nenechávejte falešná data ve finální aplikaci.

U problémů pouze v produkčním prostředí porovnejte přesný nasazený commit, konfiguraci Node/runtime, proměnné prostředí, dostupnost sítě a verze závislostí. Pokud platforma hlásí chybový kód specifický pro poskytovatele, použijte oficiální dokumentaci tohoto poskytovatele pro tento přesný kód, místo abyste předpokládali, že každá chyba 500 má stejnou příčinu.

Klíčové pravidlo pro řešení problémů je jednoduché: považujte „Interní chybu 500“ za příznak. Užitečným důkazem je serverová výjimka, která k ní bezprostředně předcházela. Nejprve najděte tuto výjimku, explicitně identifikujte selhávající závislost, opravte prostředí nebo hranici kódu, která ji vyvolala, a ověřte výsledek ve stejném runtime, kde k problému došlo.