Hata yönetimi

İki Tür Hata

Next.js hataları ikiye ayırır ve ikisini farklı ele alır:¹

Beklenen Hatalar: Değer Döndürün

Server Action'da doğrulama hatası için throw etmeyin; useActionState'e bir mesaj döndürün. Doküman bu durumda try/catch ve throw yerine hatayı dönüş değeri olarak modellemeyi önerir.¹ Örneği Server Actions dersinde gördünüz.

Server Component'te de aynı mantık geçerli: yanıt başarısızsa bir mesaj render edin.

async function Reviews({ slug }: { slug: string }) {
  const res = await fetch(`https://api.example.com/reviews/${slug}`);
  if (!res.ok) return <p>Yorumlar şu an yüklenemiyor.</p>;

  const reviews: Review[] = await res.json();
  return <ReviewList reviews={reviews} />;
}

Bulunamadı: notFound

Olmayan bir ürüne gelindiğinde notFound() çağırın. En yakın not-found.tsx gösterilir.¹ ProductDetails, Navigasyon ve prefetch dersindeki gibi sayfanın <Suspense>'i içinde render ediliyor.

// app/products/[slug]/page.tsx
import { notFound } from "next/navigation";

async function ProductDetails({ params }: Pick<PageProps<"/products/[slug]">, "params">) {
  const { slug } = await params;
  const product = await getProduct(slug);
  if (!product) notFound();

  return <h1>{product.name}</h1>;
}

// app/products/[slug]/not-found.tsx
import Link from "next/link";

export default function ProductNotFound() {
  return (
    <>
      <h1>Ürün bulunamadı</h1>
      <Link href="/products">Tüm ürünler</Link>
    </>
  );
}

Beklenmeyen Hatalar: error.tsx

Bir segmente error.tsx eklemek, o segmenti bir Error Boundary ile sarar. Hata en yakın üst sınıra kadar çıkar; böylece hatayı sayfanın bir bölümüyle sınırlayabilirsiniz. Error Boundary'ler Client Component olmalıdır.⁴

// app/products/error.tsx
"use client";

import { useEffect } from "react";

export default function ProductsError({
  error,
  retry,
}: {
  error: unknown;
  retry: () => void;
}) {
  useEffect(() => {
    console.error(error); // hata izleme servisine gönderin
  }, [error]);

  return (
    <>
      <h2>Ürünler yüklenemedi.</h2>
      <button onClick={() => retry()}>Tekrar dene</button>
    </>
  );
}

Üç ayrıntı:⁴

• retry(), segmentin verisini yeniden çekip tekrar render eder. 16.3'te kararlı hâle geldi. Eski örneklerdeki reset() yalnızca hata durumunu temizler, veriyi tekrar çekmez.

• error tipi unknown'dır. message okumadan önce instanceof Error ile daraltın.

• Production'da Server Component hataları genel bir mesajla gelir; ayrıntı sızmasın diye. error.digest, sunucu loglarındaki kaydı bulmanızı sağlar.

Kök layout'taki hataları yakalamak için app/global-error.tsx var. Kök layout'un yerini aldığı için kendi <html> ve <body> etiketlerini yazar.¹

Component Seviyesinde: catchError

Bir sayfadaki tek bir bölümü (öneriler, yorumlar) korumak için dosya kuralı yerine catchError kullanabilirsiniz. 16.3'te kararlı hâle geldi.⁵

// components/section-boundary.tsx
"use client";

import { catchError, type ErrorInfo } from "next/error";

function SectionError(props: { title: string }, { retry }: ErrorInfo) {
  return (
    <div role="alert">
      <p>{props.title} yüklenemedi.</p>
      <button onClick={() => retry()}>Tekrar dene</button>
    </div>
  );
}

export default catchError(SectionError);

<SectionBoundary title="Öneriler">
  <Recommendations />
</SectionBoundary>

Kendi Error Boundary class'ınızdan farkı: redirect() ve notFound()'u yanlışlıkla yakalamaz, retry() ile veriyi yeniden çeker ve başka bir sayfaya geçince hata durumu kendiliğinden temizlenir.⁵

Hata Sınırının Yakalamadıkları

Error Boundary'ler render sırasındaki hataları yakalar. Bir onClick içindeki hata yakalanmaz; onu try/catch ile yakalayıp state'te tutun. startTransition içinde fırlatılan hata ise en yakın sınıra gider.¹ Canlı ortamda hataları toplamak Production'a Hazırlık rehberinin konusu.

Kendin Dene

• getProducts'ın içine throw new Error("db down") yazın. error.tsx görünüyor mu? Header yerinde duruyor mu?

• Hatayı yalnızca ilk çağrıda fırlatacak şekilde değiştirin ve Tekrar dene'ye basın.

• next build && next start ile çalıştırıp error nesnesinin mesajına bakın. Geliştirmedekiyle aynı mı?

• notFound()'u bir try bloğuna alın. Ne oluyor?

Detaylı Öğrenmek İçin

• Resmi doküman: "Error Handling" sayfası; beklenen ve beklenmeyen hatalar, iç içe sınırlar ve global-error.¹

• Resmi doküman: error.js referansı; retry ile reset farkı ve özel hata sınırı örneği.⁴

• Resmi doküman: React'in Error Boundary anlatımı; sınırın yakaladığı ve yakalamadığı hatalar.⁶