React Error Boundary: Render-Fehler mit Fallback abfangen

Eine Error Boundary ist eine React-Komponente, die Fehler abfängt, die beim Rendern der Komponenten in ihr geworfen werden, und eine Fallback-UI zeigt, statt die ganze App abstürzen zu lassen. Sie muss eine Klassenkomponente sein, die static getDerivedStateFromError definiert, weil es dafür keinen Hook gibt. Du schreibst sie einmal und legst sie um jeden beliebigen Teil des Baums.

Drück „Break the profile“, damit das Kind beim Rendern einen Fehler wirft.

// This throws on purpose: Profile throws during render after you press the button.
import { Component, useState } from 'react';

class ErrorBoundary extends Component {
    state = { error: null };

    static getDerivedStateFromError(error) {
        return { error };
    }

    componentDidCatch(error, info) {
        console.log('caught:', error.message);
    }

    reset = () => {
        this.props.onReset();
        this.setState({ error: null });
    };

    render() {
        if (this.state.error) {
            return (
                <div style={{ padding: 12, background: '#fdecea' }}>
                    <p>Something went wrong: {this.state.error.message}</p>
                    <button onClick={this.reset}>Try again</button>
                </div>
            );
        }
        return this.props.children;
    }
}

function Profile({ broken }) {
    if (broken) {
        throw new Error('Profile could not render');
    }
    return <p>Ada Lovelace, mathematician</p>;
}

export default function App() {
    const [broken, setBroken] = useState(false);

    return (
        <div>
            <button onClick={() => setBroken(true)}>Break the profile</button>
            <p>This line is outside the boundary and stays.</p>
            <ErrorBoundary onReset={() => setBroken(false)}>
                <Profile broken={broken} />
            </ErrorBoundary>
        </div>
    );
}

Das Profil wird durch den Fallback ersetzt, und der Rest der Seite funktioniert weiter. Die Konsole zeigt den Fehler zweimal: React loggt jeden abgefangenen Fehler mit console.error, und componentDidCatch loggt ihn noch einmal. „Try again“ beseitigt die Ursache (broken) und den Fehler der Boundary, also rendert das Profil wieder. Entferne this.props.onReset(); aus reset, und Try again springt sofort zurück in den Fallback, weil nichts die Ursache behoben hat.

Wie die Klasse funktioniert

Zwei Methoden machen eine Klasse zur Error Boundary:

• static getDerivedStateFromError(error) läuft beim Rendern, direkt nachdem ein Kind einen Fehler geworfen hat. Sie gibt das State-Update zurück, das die Boundary auf ihren Fallback umschaltet. Sie muss pur sein: kein Logging, keine Anfragen.
• componentDidCatch(error, info) läuft, nachdem der Fallback auf dem Bildschirm ist. Nutze sie für Nebeneffekte wie das Senden des Fehlers an einen Reporting-Dienst. info.componentStack listet die Komponente, die den Fehler geworfen hat, und die Komponenten darüber.

class ErrorBoundary extends Component {
    state = { error: null };

    static getDerivedStateFromError(error) {
        return { error }; // switch to the fallback
    }

    componentDidCatch(error, info) {
        reportError(error, info.componentStack); // your logging service
    }

    render() {
        if (this.state.error) return this.props.fallback;
        return this.props.children;
    }
}

Es gibt kein Hook-Gegenstück, also braucht selbst eine App, die nur aus Funktionskomponenten besteht, diese eine Klasse. Die Seite zu Klassenkomponenten erklärt die Klassensyntax, falls sie dir neu ist.

Was eine Boundary abfängt und was nicht

Eine Boundary fängt Fehler ab, die passieren, während React an den Komponenten in ihr arbeitet:

• beim Rendern (dem Körper einer Funktionskomponente, dem render einer Klasse),
• in Lifecycle-Methoden und Konstruktoren von Kind-Klassenkomponenten,
• in Effekten (useEffect, useLayoutEffect) und Ref-Callbacks,
• ein abgelehntes Promise, das mit use gelesen wird, und in React 19 einen Fehler, den eine Form Action oder eine an das startTransition aus useTransition übergebene Funktion wirft.

Sie fängt nicht ab:

• Fehler in Event-Handlern,
• async-Code, den du selbst startest: setTimeout, .then()-Callbacks, ein await in einem Event-Handler,
• Fehler im eigenen render der Boundary (die fängt die nächste Boundary darüber ab),
• Fehler beim Server-Rendering.

Event-Handler sind ausgenommen, weil sie das Rendern nicht kaputt machen. Der Bildschirm ist weiterhin in einem gültigen Zustand, also reicht ein try/catch im Handler. Wenn die Boundary trotzdem erscheinen soll, speichere den Fehler im State und wirf ihn beim nächsten Render:

// This throws on purpose: the second button forwards an async error to the boundary.
import { Component, useState } from 'react';

class ErrorBoundary extends Component {
    state = { error: null };
    static getDerivedStateFromError(error) {
        return { error };
    }
    render() {
        if (this.state.error) return <p style={{ color: 'crimson' }}>Boundary: {this.state.error.message}</p>;
        return this.props.children;
    }
}

function loadReport() {
    // Stands in for a request that fails
    return new Promise((_, reject) => setTimeout(() => reject(new Error('Report failed to load')), 150));
}

function Report() {
    const [error, setError] = useState(null);
    if (error) throw error; // thrown during render, so the boundary sees it

    async function handleUnsafe() {
        await loadReport(); // rejects: the boundary never hears about it
    }

    async function handleForwarded() {
        try {
            await loadReport();
        } catch (e) {
            setError(e);
        }
    }

    return (
        <div>
            <button onClick={handleUnsafe}>Load (error escapes)</button>
            <button onClick={handleForwarded}>Load (error forwarded)</button>
        </div>
    );
}

export default function App() {
    return (
        <ErrorBoundary>
            <Report />
        </ErrorBoundary>
    );
}

Der erste Button lässt die Buttons auf dem Bildschirm und gibt in der Konsole nur einen nicht abgefangenen Fehler aus. Der zweite fängt die Ablehnung ab, speichert sie, und die Boundary übernimmt.

Wohin Boundaries gehören

Eine Boundary um die ganze App verhindert den weißen Bildschirm, aber dann ersetzt jeder kleine Fehler alles. Setze Boundaries um Teile, die unabhängig voneinander scheitern können: ein Widget in der Seitenleiste, ein Diagramm, jede Route. Ein Fehler kostet dann ein Panel, nicht die Seite.

// This throws on purpose: the Stocks widget fails during render.
import { Component } from 'react';

class ErrorBoundary extends Component {
    state = { error: null };
    static getDerivedStateFromError(error) {
        return { error };
    }
    render() {
        if (this.state.error) {
            return <div style={{ padding: 8, background: '#fdecea' }}>{this.props.name} is unavailable.</div>;
        }
        return this.props.children;
    }
}

function Weather() {
    return <div style={{ padding: 8, background: '#eef6ee' }}>Weather: 21 °C</div>;
}

function Stocks() {
    const prices = undefined; // imagine the data came back empty
    return <div style={{ padding: 8 }}>Stocks: {prices.length} prices</div>;
}

export default function App() {
    return (
        <div style={{ display: 'grid', gap: 8 }}>
            <ErrorBoundary name="Weather">
                <Weather />
            </ErrorBoundary>
            <ErrorBoundary name="Stocks">
                <Stocks />
            </ErrorBoundary>
        </div>
    );
}

Nur das Panel Stocks zeigt seinen Fallback. Verschiebe beide Widgets in eine <ErrorBoundary>, und das funktionierende Panel Weather verschwindet mit.

Ohne jede Boundary entfernt React den ganzen Baum vom Bildschirm, wenn ein Render-Fehler nicht abgefangen wird. Eine leere Seite ist sicherer als eine kaputte, die falsche Daten zeigt, aber Nutzer lesen sie als Absturz.

Die Bibliothek react-error-boundary

Das Paket react-error-boundary verpackt die Klasse für dich und ergänzt Helfer zum Zurücksetzen. In diesem Editor ist es nicht verfügbar, deshalb steht es hier in einem statischen Block:

import { ErrorBoundary, useErrorBoundary } from 'react-error-boundary';

function Fallback({ error, resetErrorBoundary }) {
    return (
        <div role="alert">
            <p>Something went wrong: {error.message}</p>
            <button onClick={resetErrorBoundary}>Try again</button>
        </div>
    );
}

<ErrorBoundary FallbackComponent={Fallback} onReset={() => refetch()} resetKeys={[userId]}>
    <Profile userId={userId} />
</ErrorBoundary>;

// Inside a child: hand an async error to the boundary
const { showBoundary } = useErrorBoundary();
fetchData().catch(showBoundary);

resetKeys setzt die Boundary zurück, wenn sich einer der aufgeführten Werte ändert, und showBoundary macht den Trick „speichern und werfen“ aus dem früheren Beispiel.

Fehler melden in React 19

React 19 meldet Fehler auf neue Weise. Von einer Boundary abgefangene Fehler werden einmal mit console.error geloggt, nicht abgefangene gehen an window.reportError. Um sie an deinen eigenen Dienst zu senden, übergib Optionen an createRoot. Jede Option ersetzt das passende Standard-Logging:

import { createRoot } from 'react-dom/client';

const root = createRoot(document.getElementById('root'), {
    onCaughtError(error, errorInfo) {
        // an error boundary caught it
        logToService('caught', error, errorInfo.componentStack);
    },
    onUncaughtError(error, errorInfo) {
        // no boundary caught it, and React removed the tree
        logToService('uncaught', error, errorInfo.componentStack);
    },
    onRecoverableError(error, errorInfo) {
        // React recovered by itself, for example after a hydration mismatch
        logToService('recovered', error, errorInfo.componentStack);
    },
});
root.render(<App />);

onRecoverableError ist für Fehler, die React ohne deine Hilfe behoben hat, etwa eine Hydration-Abweichung oder einen Render-Fehler, der verschwand, als React es erneut versuchte. hydrateRoot nimmt dieselben drei Optionen.

Typische Fehler

Die Boundary in die Komponente setzen, die den Fehler wirft. Eine Boundary fängt nur Fehler ihrer Kinder ab. Wenn Profile eine <ErrorBoundary> um sein eigenes JSX rendert und dann in seinem eigenen Körper einen Fehler wirft, geht der Fehler an ihr vorbei zur nächsten Boundary darüber. Umschließe die Komponente von ihrem Elternteil aus.

Nebeneffekte in getDerivedStateFromError. Die Methode läuft beim Rendern und kann mehr als einmal laufen, also beschränke sie auf das Zurückgeben von State. Logging gehört in componentDidCatch oder in das onCaughtError des Roots.

Ein Zurücksetzen, das nichts behebt. Den Fehler der Boundary zu löschen rendert dieselben Kinder mit denselben Props. Werfen sie erneut, landet man wieder beim Fallback. Ändere zuerst, was den Fehler verursacht hat (neu laden, falsche Eingaben löschen, den key ändern), und lösche dann den Fehler, wie das erste Beispiel es mit onReset tut.

Eine Boundary für die ganze App und sonst nichts. Sie verhindert die leere Seite, macht aber jeden kleinen Fehler zu einem ganzseitigen Fehler. Füge Boundaries um Features hinzu und behalte die oberste als letzte Rettung.

Fallbacks, die den Fehler vor dir verstecken. Eine freundliche Meldung ist für Nutzer richtig, aber sorg dafür, dass der Fehler trotzdem deine Logs erreicht. React 19 loggt abgefangene Fehler standardmäßig in die Konsole; in der Produktion ist diese Konsole die deiner Nutzer, also sende Fehler aus componentDidCatch oder onCaughtError an einen Dienst.

Error Boundaries passen natürlich zu <Suspense>: Suspense kümmert sich um „noch nicht bereit“, die Boundary um „fehlgeschlagen“. Setze die Boundary außerhalb von Suspense, wie in den Beispielen zu use, damit eine Komponente Laden, Erfolg und Fehlschlag abdeckt.