Next.js-Fehlergrenzen mit Wiederholfunktion, die Nutzer wieder arbeiten lassen

Warum leere Bildschirme Nutzer (und Vertrauen) kosten

Wenn eine App abstürzt und nur ein leerer Bildschirm angezeigt wird, denken die meisten Leute, sie hätten etwas falsch gemacht. Sie drücken zurück, aktualisieren die Seite oder schließen den Tab — und meistens kommen sie nicht wieder.

Der eigentliche Schaden ist nicht der Fehler selbst, sondern die Unsicherheit: „Wurde meine Arbeit gespeichert?“, „Ist mein Konto kaputt?“, „Ist das sicher zu benutzen?“ Ein stiller Fehler lehrt Nutzer, nicht mehr jedem Button zu vertrauen.

Leere Bildschirme verbergen außerdem genau das, was in dem Moment am wichtigsten ist: den nächsten Schritt. Wenn der Checkout ausfällt, braucht der Nutzer eine Möglichkeit, es erneut zu versuchen. Wenn eine Formularübermittlung fehlschlägt, muss er wissen, ob die Anfrage durchging und wie er vermeiden kann, alles neu einzugeben.

Wiederherstellung ist wichtiger als perfekte Formulierungen, weil Menschen versuchen, eine Aufgabe zu beenden, nicht eine Erklärung zu lesen. Eine gute Fehlererfahrung hält die App nutzbar, wenn möglich. Wenn das nicht möglich ist, leitet sie den Nutzer zur bestmöglichen nächsten Aktion.

Ein praktisches Ziel für eine Fallback-UI:

• Erkläre in einfachen Worten, was passiert ist
• Biete eine einzige klare Aktion an (Erneut versuchen, Seite neu laden, Zurück)
• Schütze ihre Arbeit (Formularzustand behalten, wenn möglich)
• Biete eine einfache Möglichkeit, Hilfe zu bekommen (mit Referenzcode)

Deshalb sind Error Boundaries mit einer Wiederhol-Option so effektiv: sie verwandeln eine Sackgasse in eine Umleitung. Schon ein einfacher „Erneut versuchen“-Button kann eine Session retten, wenn der Absturz durch ein temporäres Netzwerkproblem oder eine instabile API verursacht wurde.

Manchmal ist es besser, einen hilfreichen Fehlerbildschirm zu zeigen, anstatt Fehler zu verbergen. Wenn deine App in Produktion kaputtgeht, hilft es nicht, so zu tun, als wäre alles in Ordnung — das verschwendet nur Nutzerzeit. Ein klarer Recovery-Screen macht aus vagen Meldungen wie „es funktioniert nicht mehr“ etwas Handfestes.

Was React- und Next.js-Error-Boundaries tatsächlich tun

Eine Error Boundary ist ein Sicherheitsnetz für deine UI. Wenn eine Komponente beim Rendern (oder in einem Lifecycle) abstürzt, kann die Boundary diesen Absturz abfangen und stattdessen einen Fallback-Bildschirm zeigen, statt die ganze Seite zu zerstören.

Einfach gesagt: sie fängt Probleme ab, die auftreten, während React versucht, den Bildschirm zu zeichnen. Sie fängt nicht Fehler in Event-Handlern (z. B. bei Klicks), nicht asynchrone Fehler, die später auftreten (wie ein abgelehntes fetch-Promise) und keine Probleme außerhalb von React (z. B. wenn eine Browser-Erweiterung Dinge kaputtmacht). Dafür braucht es eigene Fehlerbehandlung.

In Next.js hilft sie außerdem, Client- und Server-Fehler zu trennen.

Client-Fehler sind Abstürze im Code, der im Browser des Nutzers läuft (eine fehlerhafte Komponente, falscher State, unerwartete Datenstruktur). Server-Fehler passieren, während Next.js die Seite auf dem Server baut (z. B. schlägt eine DB-Abfrage fehl, eine API timeouts, Auth-Checks werfen).

Eine gute Fallback-UI sollte einer echten Person helfen, den nächsten Schritt zu machen:

• Sage in einfachen Worten, was passiert ist (keine Stacktraces)
• Biete eine Aktion wie Erneut versuchen oder Seite neu laden an
• Halte den Rest der Seite nutzbar, wenn möglich
• Gib einen kurzen Support-Code, damit jemand helfen kann

Der größte Gewinn ist, die Blast-Range zu reduzieren. Statt dass ein fehlerhaftes Widget den Checkout komplett kaputtmacht, fällt nur dieses Widget aus, während Warenkorb, Navigation und Formularfelder weiter funktionieren.

Das Recovery-first-Muster: Nachricht + Aktion + Kontext

Eine gute Error Boundary ist nicht nur ein Absturzfänger. Sie ist ein Wiederherstellungsbildschirm, der jemandem hilft, die Aufgabe zu beenden. Das Ziel ist, Panik zu reduzieren, eine sichere nächste Aktion anzubieten und genug Details zu erfassen, um die Ursache zu beheben.

Ein recovery-orientierter Fallback hat drei Zutaten: eine klare Nachricht, eine sichere Aktion, die der Nutzer sofort machen kann, und ein kleines Stück Kontext, das er mit dem Support teilen kann (z. B. eine Referenz-ID).

Fange mit der Aktion an, nicht mit der Entschuldigung. Wenn ein Abschnitt der Seite fehlschlägt, ermögliche dem Nutzer, genau diesen Abschnitt erneut zu laden. Wenn die ganze Route fehlgeschlagen ist, biete Seite neu laden oder Zurück an. Halte Aktionen risikoarm: sie sollten keine Daten löschen oder versehentlich einen Kauf wiederholen.

Für die Nachricht: sage dem Nutzer, was er wissen muss, nicht, was der Code weiß. Vermeide Stacktraces, Komponentennamen oder „TypeError: undefined is not a function“. Eine bessere Nachricht ist: „Wir konnten deine Projekte nicht laden. Deine Änderungen sind gespeichert. Versuche es erneut.“

Dann füge Kontext hinzu, der aus einer vagen Bug-Meldung etwas Debugbares macht. Zeige eine kurze Referenz-ID wie ERR-7F3A2C und einen Zeitstempel. Wenn du dieselbe ID in den Logs vermerkst, kann der Support den passenden Fehler schnell finden.

Plane deine Boundaries, bevor du Code schreibst

Error Boundaries wirken am besten, wenn du sie als Produkt-Feature betrachtest und nicht als Notlösung. Bevor du Komponenten hinzufügst, entscheide, was „Wiederherstellung“ für jeden Teil der App bedeutet.

Beginne damit, abzubilden, wo Fehler eingegrenzt werden sollten. Eine Boundary auf Seitenebene ist nützlich, wenn die ganze Route von einer Anfrage oder einem kritischen Layout abhängt. Kleinere, komponentenbezogene Boundaries sind besser, wenn du den Rest der Seite nutzbar halten kannst (z. B. die Sidebar lädt, der Activity Feed fällt aus).

Eine einfache Platzierungsregel:

• Setze eine Boundary auf Seiten- oder Routenebene für kritische Flows wie Checkout, Login oder Einstellungen speichern.
• Setze Boundaries um optionale Widgets wie Empfehlungen, Charts oder Kommentare.
• Füge Boundaries um riskante Integrationen wie Third-Party-SDKs, eingebettete Editoren und Dateiuploads hinzu.
• Vermeide es, jede Mini-Komponente zu umwickeln. Das macht Fehler schwieriger zu verstehen.

Definiere als Nächstes, was Retry tatsächlich tun soll. Retry sollte vorhersehbar sein: den Segment-Render neu auslösen, Daten neu abrufen oder einen bestimmten State-Abschnitt zurücksetzen. Wenn Retry nur denselben kaputten State abspielt, werden Nutzer den Button spammen und stecken bleiben.

Mache das Verhalten explizit mit einer einfachen Regel: „Retry setzt X zurück und lädt Y neu.“ Zum Beispiel: Wenn „Profil speichern“ fehlschlägt, sollte Retry die Save-Anfrage neu ausführen und das Formular wieder aktivieren, nicht das, was der Nutzer eingegeben hat, löschen.

Entscheide schließlich, welchen Kontext du für den Support erfasst und was du niemals zeigen wirst. Hilfreicher Kontext kann so einfach sein wie Routen-/Bildschirmname, welche Aktion der Nutzer zuletzt gemacht hat, Zeitstempel und Umgebung (prod vs staging) und ein kurzer Fehlercode. Ziehe klare Grenzen: zeige niemals Secrets, Tokens, vollständige Request-Bodies oder persönliche Daten in der UI.

Schritt-für-Schritt: Error Boundaries mit Wiederholung in Next.js hinzufügen

Eine gute Error Boundary macht zwei Dinge: sie sagt dem Nutzer in einfachen Worten, was passiert ist, und sie gibt ihm einen klaren nächsten Schritt (Erneut versuchen oder zurückgehen). Hier sind zwei praktische Wege, das hinzuzufügen.

App Router: error.tsx + reset()

Im App Router füge eine error.tsx-Datei in das Routen-Segment, das du schützen möchtest. Next.js rendert sie, wenn in diesem Segment etwas wirft.

'use client'

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    \u003cdiv style={{ padding: 16 }}\u003e
      \u003ch2\u003eSomething went wrong\u003c/h2\u003e
      \u003cp\u003eTry again. If it keeps happening, you can go back to a stable page.\u003c/p\u003e

      \u003cdiv style={{ display: 'flex', gap: 8, marginTop: 12 }}\u003e
        \u003cbutton onClick={() => reset()}\u003eRetry\u003c/button\u003e
        \u003cbutton onClick={() => (window.location.href = '/')}\u003eGo to Home\u003c/button\u003e
      \u003c/div\u003e

      \u003cp style={{ marginTop: 12, fontSize: 12, opacity: 0.8 }}\u003e
        Error code: {error.digest ?? 'unknown'}
      \u003c/p\u003e
    \u003c/div\u003e
  )
}

Verwende benutzerfreundliche Labels. „Erneut versuchen“ ist klarer als „Boundary zurücksetzen“ und „Zur Startseite“ ist sicherer, damit niemand stecken bleibt.

Pages Router: wiederverwendbare ErrorBoundary-Komponente

Wenn du den Pages Router nutzt (oder einen Wrapper um ein spezielles Widget legen willst), benutze eine React-Klassenkomponente.

import React from 'react'

type Props = { children: React.ReactNode; fallback?: React.ReactNode }

type State = { hasError: boolean }

export class ErrorBoundary extends React.Component<Props, State> {
  state: State = { hasError: false }

  static getDerivedStateFromError() {
    return { hasError: true }
  }

  retry = () => this.setState({ hasError: false })

  render() {
    if (this.state.hasError) {
      return (
        this.props.fallback ?? (
          \u003cdiv style={{ padding: 16 }}\u003e
            \u003ch2\u003eWe hit a problem\u003c/h2\u003e
            \u003cp\u003eYou can retry, or go back to a stable page.\u003c/p\u003e
            \u003cbutton onClick={this.retry}\u003eRetry\u003c/button\u003e{' '}
            \u003cbutton onClick={() => (window.location.href = '/')}\u003eGo to Home\u003c/button\u003e
          \u003c/div\u003e
        )
      )
    }

    return this.props.children
  }
}

Platziere diese Boundary um den kleinstmöglichen riskanten Bereich (ein komplexes Formular, ein Zahlungs-Widget oder ein datenintensives Panel), damit der Rest der Seite nutzbar bleibt.

Support-Kontext hinzufügen, ohne sensible Daten zu zeigen

Wenn etwas fehlschlägt, wollen Nutzer keine Mysterien. Gib ihnen eine einfache Referenz, die sie teilen können, und erfasse genug Kontext, um das Problem zu reproduzieren.

Beginne damit, eine Fehler-ID zu generieren (eine kurze zufällige Zeichenfolge oder UUID). Zeige sie in der Fallback-UI als „Error ID: ABC123“ und mache sie leicht kopierbar. Wenn der Nutzer auf Erneut versuchen klickt, behalte dieselbe ID, damit du den ersten Fehler mit dem Retry-Versuch in deinen Logs verknüpfen kannst.

Erfasse leichten Kontext, der beantwortet: Wo war der Nutzer, was wollte er tun und wann ist es passiert? Meist reichen wenige Felder aus:

• Route oder Seite (z. B. /settings/billing)
• Funktionsbereich (Billing, Checkout, Editor)
• Letzte Nutzeraktion (Klick auf „Speichern“, Formular abgeschickt)
• Zeitstempel und Zeitzone
• App-Build/Version

Sende oder speichere die detaillierten Fehler sicher. Eine gute Regel: Wenn du es nicht in einen öffentlichen Chat einfügen würdest, sammle es nicht automatisch. Vermeide Secrets (API-Keys, Tokens), vollständige Request-Bodies, Passwörter, Zahlungsdetails und rohe Cookies. Wenn du serverseitig loggst, bevorzuge Redaction und Allowlists (nur die Felder loggen, die du erwartest).

Wenn du eine „Diesen Fehler melden“- oder „Support kontaktieren“-Option im Fehler-UI hinzufügst, fülle die Fehlermeldung und den Basis-Kontext vor, damit der Nutzer nicht alles selbst erklären muss.

Eine fallback-UI designen, die Nutzer wirklich nutzen können

Ein guter Fehlerbildschirm sollte sich wie eine sichere Landung anfühlen, nicht wie eine Sackgasse. Vermeide technische Begriffe und beschuldige den Nutzer nicht. „Etwas ist schiefgelaufen“ ist ausreichend. „Unexpected token in JSON“ ist unnötig.

Halte die Seitenstruktur vertraut, damit es sich weiterhin wie deine App anfühlt. Bewahre Header, Navigation und den Platz, wo normalerweise Inhalt steht. Wenn das Layout stabil bleibt, versuchen Nutzer eher, es erneut zu versuchen, statt die Seite zu verlassen.

Mache den nächsten Schritt offensichtlich. Der primäre Button sollte das visuelle Zentrum sein, nicht ein winziger Textlink. Setze die primäre Aktion an erste Stelle und benenne sie klar.

Eine einfache Menge von Aktionen, die die meisten Fälle abdeckt:

• Erneut versuchen
• Zurückgehen
• Seite neu laden
• Support kontaktieren

Füge einen kurzen Satz hinzu, der erklärt, was beim Retry passiert (z. B. „Wir versuchen, deine Daten erneut zu laden“). Wenn Daten verloren gehen könnten, sag das klar und biete eine sichere Option wie „Details kopieren“ oder „Als Entwurf speichern“, falls vorhanden.

Barrierefreiheit ist wichtig. Wenn der Fallback erscheint, setze die Tastaturfokus auf die Überschrift oder den primären Button, damit Screenreader- und Tastaturnutzer merken, dass sich etwas geändert hat. Sorge für ausreichenden Kontrast, große Tap-Ziele und dass Enter/Space den Hauptbutton aktivieren.

Füge abschließend kleinen, nicht-sensiblen Kontext hinzu, der dem Support hilft ohne Nutzer zu verunsichern: einen Zeitstempel, einen kurzen Referenzcode und was der Nutzer gerade versucht hat (z. B. „Einstellungen speichern“).

Häufige Fehler (und wie man sie vermeidet)

Error Boundaries sollen Nutzer schützen, nicht Probleme verbergen. Ein freundlicher Screen hilft nicht, wenn derselbe Bug immer wieder auftritt — dann wandert der Schmerz nur zu Support.

Die größten Fehler sind oft einfach.

Fehler, die die Lage heimlich verschlechtern

• Zu viel abfangen: Eine app-weite Boundary kann ein kleines „Profil-Widget fehlgeschlagen“ in einen kompletten Seitenabsturz verwandeln. Setze Boundaries um Features, damit der Rest der Seite weiterarbeitet.
• Retry ohne Ausweg: Wenn Retry immer wieder fehlschlägt, fühlen sich Nutzer gefangen. Nach 1–2 Versuchen biete einen anderen Pfad an (Zurück, Seite neu laden, Support kontaktieren).
• Rohes Fehler-Text anzeigen: Stacktraces und Datenbankmeldungen verunsichern Nutzer und können Details leaken. Zeige eine einfache Nachricht und lagere technische Infos in Logs.
• Keine Fehler-ID: Wenn Support nicht das, was der Nutzer gesehen hat, mit dem Log verknüpfen kann, wird die Fehleranalyse zu Ratespiel.
• Einheitlicher Fallback für alles: „Etwas ist schiefgelaufen“ überall trainiert Nutzer, die App zu verlassen. Passe den Fallback an die Funktion an: Speichern, Laden, Auth, Zahlungen.

Wie man sie vermeidet (einfache Regeln)

Behandle Retry als Recovery-Tool, nicht als Reset-Button. Deaktiviere den Retry-Button während des Retry-Vorgangs und ändere die Nachricht, wenn es erneut fehlschlägt.

Füge Support-Kontext hinzu, der beim Debuggen hilft ohne Secrets zu zeigen: Fehler-ID, Zeit, Seiten- oder Funktionsname und die letzte Aktion. Halte Tokens, E-Mails und vollständige Payloads aus der UI raus.

Teste den Fehlerpfad absichtlich. Schalte dein Netzwerk aus, erzwinge einen 500-Status und bestätige, dass die UI dem Nutzer einen klaren nächsten Schritt bietet und Support etwas Nachvollziehbares hat.

Schnelle Checkliste vor dem Release

Bevor du Error Boundaries mit Retry auslieferst, mach einen Durchgang mit Fokus auf echte Wiederherstellung. Du willst zwei Dinge beweisen: das Fallback erscheint, wenn es sollte, und der Nutzer hat einen klaren Weg zurück zu seiner Arbeit.

Erzeuge absichtlich einen kontrollierten Fehler (z. B. wirf innerhalb einer Komponente, die normalerweise Daten lädt). Prüfe dann:

• Das Fallback rendert mit einer klaren Nachricht (keine Stacktraces).
• Retry stellt entweder vollständig wieder her oder schlägt erneut mit einer ruhigen, konsistenten UI fehl.
• Eine Fehler-ID wird dem Nutzer gezeigt und erscheint in den Logs.
• UI und Logs enthalten keine Secrets oder persönliche Daten (Tokens, E-Mails, komplette Queries, Request-Header).
• Der Flow funktioniert auf dem Handy und bei langsamer Verbindung. Buttons sollten gut zu treffen sein und Retry darf keine Anfragen spammen.

Stelle sicher, dass Retry festgefahrene Lade-Zustände zurücksetzt, sich während des Laufs deaktiviert und einen kurzen Status wie „Erneut versuchen…“ zeigt. Wenn Retry nicht funktioniert (offline, fehlende Berechtigungen), sage das und biete eine sichere nächste Aktion an.

Ein realistisches Beispiel: „Speichern fehlgeschlagen“, ohne den Nutzer zu verlieren

Ein Nutzer bearbeitet seine Rechnungsadresse und klickt auf Speichern. Die Anfrage trifft auf ein instabiles Backend, liefert einen 500er zurück und ein Teil der UI wirft einen Fehler. Ohne Boundary kann die Seite in einen leeren Bildschirm abstürzen. Der Nutzer ist unsicher, ob seine Änderungen gespeichert wurden und bricht wahrscheinlich den Vorgang ab.

Mit einem recovery-orientierten Ansatz fängt die Error Boundary den Absturz ab und zeigt ein Fallback, das den Nutzer orientiert. Das Formular bleibt nach Möglichkeit sichtbar (oder es rendert mit den zuletzt eingegebenen Werten neu) und die Nachricht ist klar: „Wir konnten deine Änderungen nicht speichern.“ Sie bietet eine offensichtliche nächste Aktion: Erneut versuchen. Wenn Retry wieder fehlschlägt, hat der Nutzer immer noch einen sicheren Ausweg wie „Zurück zum Dashboard“ oder „Änderungen verwerfen“.

Nützlich macht das die zusätzliche Kontextinformation, die mit dem Fehler mitläuft, ohne sensible Daten preiszugeben:

• Der Nutzer sieht eine kurze Nachricht, einen Erneut-Button und einen klaren Ausweg.
• Der Nutzer sieht eine Fehler-ID, die er kopieren kann (Beispiel: FM-8K2Q), wenn er den Support kontaktiert.
• Der Support sieht die Fehler-ID plus Basis-Kontext: Route, Zeitstempel, App-Version, Browser und die letzte Aktion.
• Support kann schneller reproduzieren, weil ihm bekannt ist, welche Anfrage fehlgeschlagen ist und in welchem UI-State die App war, ohne dass der Nutzer alles erklären muss.

Nächste Schritte: sicher ausrollen und Hilfe holen, wenn es chaotisch ist

Behandle Error Boundaries wie jede andere nutzerrelevante Funktion: rolle sie in kleinen Schritten aus, beobachte das Verhalten und weite sie dann aus.

Beginne mit einem besonders fragilen Flow, in dem ein Absturz am meisten schadet — z. B. Checkout, Login oder Speichern. Füge eine Boundary hinzu, stelle sicher, dass das Fallback in einfachen Worten erklärt, was passiert ist, und bestätige, dass Retry wirklich etwas Sinnvolles macht (nicht nur denselben Absturz erneut auslöst).

Bevor du überall Boundaries setzt, definiere Ownership. Jemand muss die Fehlertexte, die Aktionen (Erneut versuchen, Zurück, Support kontaktieren) und den Support-Kontext überprüfen, damit er nützlich und sicher bleibt.

Wenn du das in einem Codebase umsetzt, das von KI-Tools generiert wurde, erwarte Überraschungen: verstrickten State, fragile Save-Flows, kaputte Auth, exponierte Secrets oder unsichere Queries, die Retry unmöglich machen. Wenn du eine schnelle Diagnose und einen praktischen Fix-Plan brauchst, hilft FixMyMess (fixmymess.ai) dabei, kaputte KI-erzeugte Prototypen in produktionsreife Software zu überführen – inklusive Code-Diagnose, Logik-Reparatur, Security-Härtung und Deployment-Vorbereitung.