Kako popraviti internu grešku 500 u Next.js Server Components

Otvorite rutu u Next.js App Router projektu, stranica je radila trenutak prije, a sada preglednik prikazuje Internu grešku poslužitelja ili HTTP 500 odgovor. Osvježavanje ne pomaže. Klijentska konzola možda neće prikazati mnogo korisnih informacija jer je do kvara došlo tijekom renderiranja Server Componenta na poslužitelju.

Ta je situacija dovoljno česta da djeluje misteriozno, ali 500 nije dijagnoza. To znači da je poslužitelj naišao na neočekivano stanje tijekom obrade zahtjeva. Next.js može vratiti 500 zbog neobrađene aplikacijske greške, a Server Components posebno je važno pregledati jer tijekom renderiranja mogu izvršavati pristup podacima, upite baze podataka, provjere autentifikacije i drugu logiku koja je dostupna samo na poslužitelju.

Napomena o verziji: kako je provjereno 11. rujna 2026., službena Next.js dokumentacija navodi Next.js 16.3.4 kao najnoviju verziju. Formulacije grešaka, preklapanja u razvoju (development overlays), ponašanje u vrijeme izvršavanja (runtime) i zapisi o implementaciji mogu se razlikovati ovisno o verziji i hosting platformi, pa koristite trag stoga (stack trace) iz vlastitog projekta kao primarni dokaz.

Što obično uzrokuje grešku 500 u Server Componentu?

U App Routeru, Next.js prema zadanim postavkama koristi Server Components. Službena dokumentacija o Server i Client Components objašnjava da se Server Components izvršavaju na poslužitelju i mogu obavljati poslove na strani poslužitelja poput pristupa podacima. Ako jedna od tih operacija baci iznimku koja nije obrađena na način koji proizvodi valjani odgovor ili rezervnu opciju (fallback), zahtjev može neuspjeti.

Korak 1: Reproducirajte neuspješnu rutu lokalno i pročitajte izlaz poslužitelja

Počnite s najlakše dostupnim dokazima. Pokrenite isti projekt lokalno s uobičajenom naredbom za razvoj, kao što je npm run dev, i zatražite točnu rutu koja ne uspijeva. Ne počinjite mijenjanjem predmemorije, nadogradnjom paketa ili brisanjem datoteka zaključavanja (lockfiles). Prvo pronađite prvu značajnu iznimku u terminalu u kojem je pokrenut Next.js.

Preglednik vam govori da je zahtjev neuspjeo; trag stoga poslužitelja vjerojatnije će vam reći zašto. Tražite prvi redak u vlastitom aplikacijskom kodu, a ne posljednji redak unutar internih dijelova okvira (frameworka). Zabilježite rutu, datoteku, broj retka, vrstu greške i događa li se kvar pri svakom zahtjevu ili samo s određenim podacima.

Ako se problem događa samo u produkciji, umjesto toga koristite zapise izvršavanja (runtime logs) svog hosta. Na Vercelu, službeni vodič za bilježenje razlikuje zapise izgradnje (build logs) od zapisa izvršavanja (runtime logs) i objašnjava da se unosi izvršavanja mogu filtrirati prema statusnom kodu i putanji zahtjeva. Vercel također dokumentira da neuspjeh poziva funkcije može vratiti 500 kada runtime sruši ili dođe do neuhvaćene iznimke ili odbijanja (rejection).

Korak 2: Izolirajte dohvaćanje podataka i učinite kvarove eksplicitnima

Server Components često ne uspijevaju dok čekaju gornji API ili bazu podataka. Službeni Next.js tutorijal za dohvaćanje podataka pokazuje Server Components koji izvršavaju asinkroni pristup podacima na strani poslužitelja. Tretirajte svaku vanjsku ovisnost kao moguće mjesto kvara.

Za fetch(), razlikujte mrežni kvar od HTTP odgovora s greškom. Odgovor s nestatusnim kodom uspjeha treba provjeriti prije parsiranja ili renderiranja njegovih podataka. Mali omotač (wrapper) čini stvarni problem vidljivim u zapisima poslužitelja:

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

Nemojte bilježiti pristupne tokene, kolačiće, zaglavlja za autorizaciju, lozinke baze podataka ili pune URL-ove koji sadrže tajne. Statusni kod, naziv cilja zahtjeva, ID korelacije i očišćena poruka o grešci obično su dovoljni za identifikaciju neuspjele ovisnosti.

Korak 3: Provjerite varijable okruženja i granicu poslužitelja/klijenta

Ako isti commit radi lokalno, ali vraća 500 nakon implementacije, usporedite okruženja prije mijenjanja aplikacijske logike. Potvrdite da svaka potrebna varijabla na strani poslužitelja postoji u cilju implementacije i da vrijednost upućuje na uslugu dostupnu iz tog runtimea. Lokalna .env datoteka ne dokazuje da produkcijska implementacija ima iste vrijednosti.

Zatim pregledajte granice komponenti. Next.js Server Components su zadani u App Routeru, dok interaktivni kod koji zahtijeva stanje (state), efekte, rukovanje događajima ili API-je dostupne samo u pregledniku pripada Client Componentu. Službeni Next.js nastavni materijal demonstrira premještanje komponente koja koristi useState iza direktive 'use client'. Neke pogreške na granici otkrivaju se tijekom kompilacije, a ne postaju greška 500, ali njihovo isključivanje sprječava vas da tretirate grešku u strukturi koda kao ispad hostinga.

Također provjerite bilo koji paket namijenjen samo poslužitelju koji pretpostavlja specifičnu Node.js mogućnost, raspored datotečnog sustava, nativni binarni kod ili mrežno okruženje. Ovisnost može raditi na jednom računalu, a ne uspijevati u drugom runtimeu ako se te pretpostavke razlikuju.

Korak 4: Dodajte odgovarajuće rukovanje greškama umjesto skrivanja iznimke

Kada je osnovni uzrok poznat, odlučite je li greška očekivana ili neočekivana. Nedostajući zapis možda zaslužuje odgovor "nije pronađeno" (not-found). Neuspjeh validacije možda zaslužuje normalnu poruku. Neočekivana iznimka treba biti zabilježena i dopušteno joj je da dosegne granicu greške, umjesto da se tiho pretvori u prazne podatke koji će negdje drugdje uzrokovati kvar.

Next.js dokumentira posebnu datoteku error.tsx kao granicu greške segmenta rute za neočekivane greške. Njezina komponenta je Client Component i može ponuditi ponovni pokušaj putem pružene reset funkcije. Službeni Next.js vodič za rukovanje greškama također demonstrira korištenje notFound() kada traženi resurs ne postoji.

'use client';

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

Granica greške poboljšava ono što korisnik vidi; ne popravlja osnovnu iznimku. Zadržite zapis na strani poslužitelja koji identificira uzrok i nemojte izlagati osjetljive tragove stoga ili tajne u korisničkom sučelju.

Korak 5: Provjerite popravak u produkcijskoj verziji sličnoj produkciji

Razvojni poslužitelj je nužan za dijagnostiku, ali nije konačni test. Nakon što ruta radi lokalno, pokrenite produkcijsku izgradnju s upraviteljem paketa svog projekta, pokrenite je u produkcijskom načinu kada je to praktično i zatražite istu rutu s istim relevantnim uvjetima podataka. Zatim provjerite implementirano okruženje s otvorenim zapisima izvršavanja.

npm run build
npm start

Ako vaša hosting platforma gradi drugačije od vašeg prijenosnog računala, također testirajte implementaciju pregleda (preview deployment) prije promocije promjene. Popravak je vjerodostojan samo kada ruta vrati očekivani status, prikaže očekivani sadržaj i ne pojavi se nova iznimka poslužitelja za taj zahtjev.

Kako potvrditi da je greška 500 stvarno popravljena

• Prethodno neuspješni URL se učitava više puta bez HTTP 500 odgovora.
• Terminal poslužitelja ili zapisi izvršavanja u produkciji više ne prikazuju izvornu iznimku.
• Isti popravak preživljava npm run build i pokretanje u produkcijskom načinu ili implementaciju pregleda.
• Potrebne varijable okruženja prisutne su u okruženju u kojem se kvar izvorno dogodio.
• Kvarovi vanjskog API-ja ili baze podataka sada proizvode kontroliranu putanju greške umjesto neobjašnjivog pada.
• Interaktivni kod dostupan samo u pregledniku nalazi se unutar Client Components, dok tajne i privilegirani pristup podacima ostaju na poslužitelju.
• Granica error.tsx korisnicima daje razumnu rezervnu opciju za neočekivane kvarove segmenta rute.

Ako i dalje ne uspijeva

Smanjite rutu dok ne prestane neuspješno raditi. Privremeno zamijenite jednu ovisnost po jednu s poznatom sigurnom vrijednošću: prvo poziv baze podataka, zatim vanjski API, zatim autentifikaciju ili pretragu sesije, zatim podređene komponente. Prva uklonjena operacija koja učini da greška 500 nestane identificira područje koje treba istražiti. Vratite svaku ovisnost nakon testiranja, umjesto da ostavite lažne podatke u konačnoj aplikaciji.

Za problem koji se događa samo u produkciji, usporedite točno implementirani commit, konfiguraciju Node/runtimea, varijable okruženja, mrežnu dostupnost i verzije ovisnosti. Ako platforma prijavljuje kod greške specifičan za pružatelja usluge, koristite službenu dokumentaciju tog pružatelja za taj točan kod, umjesto da pretpostavljate da svaka greška 500 ima isti uzrok.

Ključno pravilo za rješavanje problema jednostavno je: tretirajte "Internu grešku 500" kao simptom. Koristan dokaz je iznimka na strani poslužitelja koja se dogodila neposredno prije nje. Prvo pronađite tu iznimku, učinite neuspjelu ovisnost eksplicitnom, ispravite okruženje ili granicu koda koja ju je pokrenula i provjerite rezultat u istom runtimeu u kojem se problem dogodio.