Next.js Error Boundary: Vollständiger Leitfaden – 5 Tipps für elegante Laufzeitfehlerbehandlung

Im Operations-Team-Chat herrscht Panik: „Die Startseite ist down! Alles weiß!“

Sie öffnen das Monitoring – eine Drittanbieter-Komponente ist ausgefallen und reißt die ganze Seite mit. Die Nutzer sehen nur ein leeres Weiß, ohne jede Fehlermeldung. Eine Seite, die in der Produktion einwandfrei lief, bricht plötzlich wegen falschen Datenformats oder eines API-Timeouts komplett zusammen. Klassisches try-catch greift auf der React-Rendering-Ebene nicht – die Nutzer starren auf einen weißen Bildschirm und schließen die Seite.

Laut UX-Forschung führt ein weißer Bildschirm dazu, dass über 80 % der Nutzer sofort abspringen.

Glücklicherweise bietet Next.js Error Boundaries, mit denen Sie Laufzeitfehler elegant behandeln können. Sie verhindern nicht nur weiße Bildschirme, sondern zeigen eine freundliche Fallback-Oberfläche – sogar mit einem „Wiederholen“-Button zur Selbstheilung. Dieser Artikel erklärt die vollständige Next.js Error Boundary-Nutzung: von error.tsx über global-error.tsx bis zu den Besonderheiten bei Server Components.

Nach dem Lesen wissen Sie, wie Ihre App bei Fehlern eleganter reagiert – und Sie vermeiden nächtliche Notfall-Deployments wegen Bugs.

Warum brauchen Sie Error Boundaries? Grenzen klassischer Fehlerbehandlung

Als ich anfing, React zu nutzen, dachte ich, try-catch würde alle Fehler abfangen. Die Realität hat mich schnell eines Besseren belehrt.

Drei Schwachstellen von try-catch

Erstens: Es fängt nur synchrone Fehler ab. JSON.parse(badData) in einem try-Block? Kein Problem. Aber ein Fehler während des Component-Renderings? Fehlanzeige.

Zweitens, und noch tückischer: asynchrone Fehler in Event Handlern. Sie rufen in einem Klick-Handler eine API auf, die ausfällt – try-catch hilft nicht. Warum? Der asynchrone Code läuft, nachdem der try-catch-Kontext längst beendet ist.

Drittens, und am kritischsten: React-Rendering-Fehler. Ihre Komponente greift in der return-Anweisung auf eine undefined-Eigenschaft zu – die Seite wird weiß. try-catch ist hier wirkungslos.

Wie React Error Boundaries funktionieren

React hat dieses Problem früh erkannt und Error Boundaries eingeführt. Das Prinzip ist einfach: Der Komponentenbaum ist wie Matroschka-Puppen – Fehler „blubbern“ von innen nach außen, bis sie die nächste Error Boundary treffen.

Klassisch schreibt man dafür eine Class Component mit componentDidCatch und getDerivedStateFromError. Ehrlich gesagt: Jedes Mal eine Class Component – nervig. Und wer heute mit Function Components arbeitet, kommt mit diesen Lifecycle-Methoden gar nicht klar.

Die elegante Next.js-Lösung

Mit dem App Router in Next.js 13 wurde Error Boundary deutlich einfacher. Sie legen einfach eine error.tsx im Route-Verzeichnis an – sie wird automatisch zur Error Boundary dieser Route. Keine Class Components, kein eigenes State-Management – Next.js erledigt das.

Entscheidend: Next.js Error Boundaries behandeln Server- und Client-Fehler gleichermaßen. Fehler beim Server-Rendering von Server Components werden ebenfalls von der nächsten error.tsx erfasst – in klassischem React nicht möglich.

Einzige Voraussetzung: error.tsx muss eine Client Component sein, mit 'use client' am Anfang. Warum? Sie braucht React Hooks für Fehlerstatus und Wiederherstellung – Hooks laufen nur clientseitig.

Facebook Messenger ist ein klassisches Beispiel. Sidebar, Chat-Fenster und Eingabefeld sind jeweils in eigene Error Boundaries gepackt. Fällt ein Bereich aus, arbeiten die anderen weiter. Viele Nutzer merken gar nicht, dass etwas schiefgelaufen ist.

Das ist der Kernwert von Error Boundaries: lokale Fehler werden nicht zu globalen Katastrophen.

KiloClaw - Managed OpenClaw für Unternehmen: AI-Agent-Orchestrierung und smartes Modell-Routing

Jetzt starten →Anzeige

error.tsx – Lokale Error Boundary

Jetzt zur Praxis. Wie schreibt man error.tsx?

Grundstruktur: In 5 Minuten startklar

Erstellen Sie error.tsx in einem beliebigen Route-Verzeichnis und fügen Sie diesen Code ein:

'use client'

import { useEffect } from 'react'

export default function Error({
  error,
  reset
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  useEffect(() => {
    // Fehler an Monitoring-Plattform melden, z. B. Sentry
    console.error('Fehler erfasst:', error)
  }, [error])

  return (
    <div className="flex flex-col items-center justify-center min-h-screen p-4">
      <h2 className="text-2xl font-bold mb-4">Ups, etwas ist schiefgelaufen</h2>
      <p className="text-gray-600 mb-4">
        {error.message || 'Seite konnte nicht geladen werden'}
      </p>
      <button
        onClick={() => reset()}
        className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
      >
        Erneut versuchen
      </button>
    </div>
  )
}

Wichtige Punkte:

1. ‘use client’ nicht vergessen: Diese Zeile am Anfang ist Pflicht, sonst meldet Next.js einen Fehler
2. error-Objekt: Enthält Fehlermeldung und Stack; digest ist neu in Next.js 15 und dient dem Error Tracking
3. reset-Funktion: Rendert den Inhalt innerhalb der Error Boundary neu – gibt Nutzern eine Chance zur Selbstheilung

Fehler-Bubbling: Schicht für Schicht nach oben

Am Anfang wirkt das etwas verwirrend. Mit dieser Verzeichnisstruktur wird es klar:

app/
├── layout.tsx          # Root-Layout
├── error.tsx           # Fängt Fehler unter Root-Route ab (A)
├── page.tsx            # Startseite
├── dashboard/
│   ├── layout.tsx      # Dashboard-Layout
│   ├── error.tsx       # Fängt Fehler unter dashboard ab (B)
│   └── page.tsx        # Dashboard-Seite
└── profile/
    └── page.tsx        # Profil-Seite

dashboard/page.tsx wirft beim Rendern einen Fehler – wer fängt ihn ab? (B) – die nächstgelegene error.tsx im Elternverzeichnis.

Und profile/page.tsx? Kein error.tsx im profile-Verzeichnis – der Fehler steigt weiter auf und wird von (A) erfasst.

Achtung: error.tsx fängt keine Fehler in layout.tsx auf derselben Ebene ab. Die Error Boundary liegt innerhalb des Layouts – wenn das Layout selbst crasht, ist die Boundary noch nicht geladen. Fehler in dashboard/layout.tsx müssen Sie in app/error.tsx behandeln.

reset() richtig einsetzen

reset() klingt magisch, rendert aber einfach den Unterbaum der Fehlerkomponente neu. Sinnvoll bei vorübergehenden Fehlern, z. B.:

• API-Timeout (Wiederholung kann gelingen)
• Netzwerk-Jitter beim Ressourcen-Laden
• Grenzfälle durch Nutzereingaben

Bei Code-Bugs wie undefined.property hilft kein Wiederholen. Dann sehen Sie den Fehler im Monitoring, fixen den Code und deployen.

Manche Teams zählen Wiederholversuche: Nach drei Mal verschwindet der Button und Nutzer werden zum Neuladen oder Support geleitet. Praktisch:

'use client'

import { useEffect, useState } from 'react'

export default function Error({ error, reset }: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  const [retryCount, setRetryCount] = useState(0)

  const handleReset = () => {
    setRetryCount(prev => prev + 1)
    reset()
  }

  return (
    <div>
      <h2>Ein Fehler ist aufgetreten</h2>
      {retryCount < 3 ? (
        <button onClick={handleReset}>
          Erneut versuchen ({retryCount}/3)
        </button>
      ) : (
        <p>Mehrfach fehlgeschlagen – bitte Seite neu laden oder <a href="/contact">Support kontaktieren</a></p>
      )}
    </div>
  )
}

global-error.tsx – Globales Sicherheitsnetz

error.tsx ist mächtig, hat aber eine Lücke: Fehler im Root-Layout app/layout.tsx werden nicht erfasst. Dafür gibt es global-error.tsx.

Wann brauchen Sie global-error.tsx?

Ehrlich gesagt wird diese Datei in der Produktion selten ausgelöst. Sie deckt vor allem zwei Katastrophenszenarien ab:

1. Root layout.tsx schlägt bei der Initialisierung fehl (z. B. globales State-Management ausgefallen)
2. Fehler, die alle error.tsx-Dateien „durchrutschen“

Ich sehe es als letztes Sicherheitsnetz – Sie hoffen, es nie zu brauchen, aber es muss da sein.

Besonderheiten von global-error.tsx

Im Gegensatz zu normaler error.tsx muss global-error.tsx eine vollständige HTML-Struktur enthalten – also <html> und <body>.

Warum? Sie ersetzt das Root-Layout komplett. Wenn das Root-Layout ausfällt, ist das gesamte Seiten-Framework weg – global-error.tsx baut eine minimal funktionsfähige Seite von Grund auf.

Vollständiger Code:

'use client'

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <html>
      <body>
        <div style={{
          display: 'flex',
          flexDirection: 'column',
          alignItems: 'center',
          justifyContent: 'center',
          minHeight: '100vh',
          padding: '20px',
          fontFamily: 'system-ui, sans-serif'
        }}>
          <h1>Schwerwiegendes Problem in der Anwendung</h1>
          <p style={{ color: '#666', marginBottom: '20px' }}>
            {process.env.NODE_ENV === 'development'
              ? error.message
              : 'Wir arbeiten daran – bitte versuchen Sie es später erneut'}
          </p>
          <button
            onClick={() => reset()}
            style={{
              padding: '10px 20px',
              background: '#0070f3',
              color: 'white',
              border: 'none',
              borderRadius: '5px',
              cursor: 'pointer'
            }}
          >
            Anwendung neu laden
          </button>
        </div>
      </body>
    </html>
  )
}

Inline-Styles statt Tailwind oder CSS Modules – bewusst so gewählt. In diesem Moment ist Ihr Stylesystem möglicherweise noch nicht geladen; rohe Styles garantieren eine lesbare Seite.

Entwicklung vs. Produktion

Wichtiges Detail: global-error.tsx greift nur in der Produktion. In der Entwicklung zeigt Next.js weiterhin die rote Fehler-Stack-Seite zum Debuggen.

In der Produktion empfehle ich, technische Details zu verbergen und nur freundliche Hinweise zu zeigen. Die process.env.NODE_ENV-Abfrage im Code dient genau dazu. Nutzer interessiert nicht „TypeError: Cannot read property ‘map’ of undefined“ – sie wollen wissen, ob die App nutzbar ist und wann es wieder funktioniert.

Brauchen Sie global-error.tsx?

Meine Empfehlung: Ja. Die Wahrscheinlichkeit ist gering, aber wenn es passiert, ist es ein Großereignis. Mit diesem Fallback sehen Nutzer wenigstens eine anständige Fehlerseite statt der Browser-Meldung „Website nicht erreichbar“.

Wie eine Versicherung – Sie hoffen, sie nie zu brauchen, aber im Ernstfall ist sie Gold wert.

Besonderheiten bei Server Components

Server Components ab Next.js 13 stellen die Fehlerbehandlung vor neue Herausforderungen. Server- und Client-Fehler werden unterschiedlich behandelt.

Alibaba Cloud - Top-Wahl für Entwickler, exklusiv 15 % Rabatt auf Lighthouse-Server

15 % Rabatt sichern →Anzeige

Wohin gehen Fehler in Server Components?

Als ich Server Components das erste Mal nutzte, war ich unsicher: Komponenten rendern auf dem Server – kann die clientseitige error.tsx das abfangen?

Ja. Next.js übermittelt Server-Fehlerinformationen an den Client und löst die nächste error.tsx aus. Wichtiger Sicherheitsmechanismus: In der Produktion werden Fehlerdetails maskiert, damit keine sensiblen Serverinformationen durchsickern.

Datenbankverbindung fehlgeschlagen? In der Entwicklung sehen Sie den vollen Stack, in der Produktion nur „Laden fehlgeschlagen“.

Erwartete vs. unerwartete Fehler

Ein zentrales Konzept, das die offizielle Dokumentation betont. Zwei Fehlertypen unterscheiden:

Erwartete Fehler: Fehler innerhalb der Geschäftslogik, die Sie explizit behandeln sollten

• Formularvalidierung (ungültiges Format)
• API gibt 404 zurück (Daten existieren nicht)
• Fehlende Berechtigung (Nutzer nicht angemeldet)

Unerwartete Fehler: Code-Bugs oder Systemausnahmen – an Error Boundary übergeben

• Datenbankverbindung fehlgeschlagen
• Drittanbieter-Dienst ausgefallen
• Zugriff auf undefined-Eigenschaften

Bei erwarteten Fehlern: try-catch in Server Action oder Datenabruf, Fehlermeldung an die Komponente zurückgeben:

// app/actions.ts
'use server'

export async function createUser(formData: FormData) {
  const email = formData.get('email') as string

  // Erwarteter Fehler: ungültiges E-Mail-Format
  if (!email.includes('@')) {
    return { error: 'Bitte geben Sie eine gültige E-Mail-Adresse ein' }
  }

  try {
    await db.user.create({ email })
    return { success: true }
  } catch (error) {
    // Unerwarteter Fehler: Datenbank ausgefallen – an Error Boundary weitergeben
    throw new Error('Benutzer konnte nicht erstellt werden')
  }
}

Bei unerwarteten Fehlern: einfach throw und zum nächsten error.tsx durchreichen lassen.

Fehlerbehandlung beim Datenabruf

So handle ich Datenabruf in Server Components:

// app/posts/page.tsx
async function getPosts() {
  const res = await fetch('https://api.example.com/posts')

  // Erwarteter Fehler: API-Fehlerstatus
  if (!res.ok) {
    // Je nach Fehlertyp: explizit behandeln oder werfen
    if (res.status === 404) {
      return { posts: [], error: 'Keine Daten vorhanden' }
    }
    // Serverfehler – an Error Boundary weitergeben
    throw new Error('Daten konnten nicht geladen werden')
  }

  return { posts: await res.json() }
}

export default async function PostsPage() {
  const { posts, error } = await getPosts()

  // Fehlerstatus explizit rendern
  if (error) {
    return <div>Keine Artikel vorhanden</div>
  }

  return (
    <ul>
      {posts.map(post => <li key={post.id}>{post.title}</li>)}
    </ul>
  )
}

Vorteil: bessere UX. „Keine Daten“ braucht keine Fehlerseite – nur echte Systemfehler lösen die error.tsx-Fallback-UI aus.

error.digest sinnvoll nutzen

Next.js 15 fügt dem error-Objekt ein digest-Feld hinzu – eine automatisch generierte eindeutige Kennung.

Nutzen? Szenario: Nutzer sieht Fehlerseite, macht Screenshot und schreibt dem Support „Seite lädt nicht“. Mit dem digest findet der Support in den Logs exakt den Request, Zeitpunkt und Fehlertyp.

In error.tsx so einsetzen:

'use client'

export default function Error({ error }: { error: Error & { digest?: string }}) {
  return (
    <div>
      <h2>Ein Fehler ist aufgetreten</h2>
      <p>Fehlernummer: {error.digest}</p>
      <p>Bitte kontaktieren Sie den Support und nennen Sie die obige Nummer</p>
    </div>
  )
}

Mit Sentry oder anderen Monitoring-Tools steigert digest die Effizienz des Error Trackings erheblich.

Best Practices für die Produktion

Nach dem „Wie“ folgt das „Wie gut“. Erfahrungen aus der Praxis.

1. Feingranulare Error Boundaries

Nicht nur eine error.tsx im Root. Kritische Bereiche sollten eigene Error Boundaries haben.

Beispiel E-Commerce:

app/
├── error.tsx                    # Fallback
├── (shop)/
│   ├── products/
│   │   └── error.tsx           # Produktliste fällt aus – Rest funktioniert
│   ├── cart/
│   │   └── error.tsx           # Warenkorb fällt aus – Produkte weiter browsbar
│   └── checkout/
│       └── error.tsx           # Checkout am kritischsten – separat behandeln

Fällt die Warenkorb-Komponente aus, können Nutzer weiter Produkte ansehen. Die ganze Site bleibt nicht blockiert.

2. Fehler-Monitoring und Reporting

useEffect in error.tsx ist der ideale Zeitpunkt fürs Reporting:

'use client'

import { useEffect } from 'react'
import * as Sentry from '@sentry/nextjs'

export default function Error({ error, reset }: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  useEffect(() => {
    // An Sentry melden
    Sentry.captureException(error, {
      tags: {
        errorDigest: error.digest,
        errorBoundary: 'app-root'
      },
      extra: {
        userAgent: navigator.userAgent,
        timestamp: new Date().toISOString()
      }
    })
  }, [error])

  return (
    // Fehler-UI...
  )
}

error.digest und Nutzerumgebung mitloggen – erleichtert die Reproduktion.

Manche Teams protokollieren die letzten besuchten Seiten (z. B. 5 URLs) – beim Debugging sehr hilfreich.

Railway - Moderne Deployment-Plattform, ohne DevOps-Aufwand, in Minuten live

Jetzt starten →Anzeige

3. Nutzerfreundliche Fehler-UI

Entwickler mögen Stack Traces – Nutzer nicht. Sie wollen wissen:

• Was ist passiert? (In einfachen Worten)
• Kann ich etwas tun? (Klare Handlungsoptionen)
• Sind meine Daten weg? (Auswirkungen erklären)

Gute Fehler-UI:

return (
  <div className="error-container">
    <h2>Seite konnte nicht geladen werden</h2>
    <p>Möglicherweise ist das Netzwerk instabil oder unser Server macht gerade Pause</p>

    <div className="actions">
      <button onClick={reset}>Erneut versuchen</button>
      <a href="/">Zur Startseite</a>
      <a href="/help">Support kontaktieren</a>
    </div>

    <details className="error-details">
      <summary>Technische Details (optional)</summary>
      <code>{error.digest}</code>
    </details>
  </div>
)

Lockerer Ton, keine unnötige Angst. „Server macht Pause“ ist freundlicher als „500 Internal Server Error“.

4. Intelligente Wiederholstrategie

Neben der Begrenzung der Versuche noch ein paar Tipps:

• Verzögertes Wiederholen: Nicht sofort reset – 1–2 Sekunden warten, dem Server Luft geben
• Exponentielles Backoff: Erst 1 s, dann 2 s, dann 4 s warten
• Fehlertyp unterscheiden: Bei Netzwerkfehlern Wiederholen empfehlen, bei Code-Fehlern direkt Support

const [retryCount, setRetryCount] = useState(0)
const [isRetrying, setIsRetrying] = useState(false)

const handleReset = async () => {
  setIsRetrying(true)
  setRetryCount(prev => prev + 1)

  // Exponentielles Backoff: 2^retryCount Sekunden
  await new Promise(resolve =>
    setTimeout(resolve, Math.pow(2, retryCount) * 1000)
  )

  setIsRetrying(false)
  reset()
}

5. Umgebungsabhängige Darstellung

Entwicklung und Produktion sollten Fehler unterschiedlich zeigen:

const isDev = process.env.NODE_ENV === 'development'

return (
  <div>
    <h2>{isDev ? error.message : 'Etwas ist schiefgelaufen'}</h2>

    {isDev && (
      <pre>
        <code>{error.stack}</code>
      </pre>
    )}

    {!isDev && (
      <p>Wir haben das Problem protokolliert und beheben es schnellstmöglich</p>
    )}
  </div>
)

Entwicklung: voller Stack zum Debuggen. Produktion: freundliche Meldung ohne technische Details.

6. Nicht übermäßig einsetzen

Zum Schluss: Error Boundaries sind Fallback, nicht die primäre Fehlerbehandlung.

Erwartete Fehler mit try-catch behandeln, nicht an Error Boundary werfen. Was lokal degradierbar ist, soll keine Fehlerseite auslösen.

Profilbild lädt nicht? Standard-Avatar anzeigen – nicht die ganze Profilseite crashen lassen.

Error Boundaries für wirklich unerwartete Fehler reservieren, die sich lokal nicht behandeln lassen.

Fazit

Kurz zusammengefasst, drei Kernpunkte:

Erstens: Error Boundaries sind Pflicht, nicht optional. Nutzerabwanderung durch weiße Bildschirme ist schlimmer, als Sie denken. Zeit in Error Boundaries zu investieren, spart nächtliche Notfall-Deployments.

Zweitens: Schichtweise behandeln. error.tsx für lokale Fehler, global-error.tsx als globales Netz, in Server Components erwartete und unerwartete Fehler trennen. Explizit behandeln, was behandelbar ist – den Rest an Error Boundaries übergeben.

Drittens: UX zuerst. Technische Details gehören ins Monitoring – Nutzer sehen freundliche, handlungsorientierte Hinweise. Ein Wiederholen-Button löst etwa 40 % der vorübergehenden Fehler – hervorragendes ROI.

Legen Sie jetzt eine error.tsx in Ihrem Next.js-Projekt an. Starten Sie im Root, erweitern Sie schrittweise auf kritische Bereiche. Mit Sentry oder ähnlichen Tools wird die Stabilität spürbar besser.

Und vergessen Sie nicht global-error.tsx. Selten ausgelöst – aber wie ein Sicherheitsgurt: Sie hoffen, ihn nie zu brauchen, aber er muss da sein.