Error boundary in React: intercettare errori con un fallback

Un error boundary è un componente React che intercetta gli errori generati durante il rendering dei componenti al suo interno e mostra una UI di fallback invece di far crollare l'intera app. Deve essere un class component che definisce static getDerivedStateFromError, perché non esiste un hook per farlo. Lo scrivi una volta e lo metti attorno a qualsiasi parte dell'albero.

Premi "Break the profile" per far generare un errore al figlio durante il rendering.

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

Il profilo viene sostituito dal fallback, e il resto della pagina continua a funzionare. La console mostra l'errore due volte: React registra ogni errore intercettato con console.error, e componentDidCatch lo registra di nuovo. "Try again" elimina la causa (broken) e l'errore del confine, quindi il profilo si renderizza di nuovo. Togli this.props.onReset(); da reset e Try again ricade subito nel fallback, perché nulla ha sistemato la causa.

Come funziona la classe

Due metodi rendono una classe un error boundary:

• static getDerivedStateFromError(error) viene eseguito durante il rendering, subito dopo che un figlio ha generato un errore. Restituisce l'aggiornamento di stato che fa passare il confine al suo fallback. Deve essere puro: niente log, niente richieste.
• componentDidCatch(error, info) viene eseguito dopo che il fallback è sullo schermo. Usalo per gli effetti collaterali come inviare l'errore a un servizio di segnalazione. info.componentStack elenca il componente che ha generato l'errore e quelli sopra di esso.

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

Non esiste un equivalente con gli hook, quindi anche un'app scritta solo con function component ha bisogno di questa unica classe. La pagina sui class component spiega la sintassi delle classi se ti è nuova.

Cosa intercetta un confine, e cosa no

Un confine intercetta gli errori che avvengono mentre React lavora sui componenti al suo interno:

• il rendering (il corpo di un function component, il render di una classe),
• i metodi del ciclo di vita e i costruttori dei class component figli,
• gli effetti (useEffect, useLayoutEffect) e i ref callback,
• una promise rifiutata letta con use e, in React 19, un errore generato da una form action o da una funzione passata allo startTransition di useTransition.

Non intercetta:

• gli errori nei gestori di eventi,
• il codice asincrono che avvii tu: setTimeout, le callback .then(), un await in un gestore di eventi,
• gli errori nel render del confine stesso (li intercetta il confine successivo più in alto),
• gli errori durante il rendering lato server.

I gestori di eventi sono esclusi perché non rompono il rendering. Lo schermo è ancora in uno stato valido, quindi basta un try/catch nel gestore. Se invece vuoi che compaia il confine, memorizza l'errore nello stato e generalo al rendering successivo:

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

Il primo pulsante lascia i pulsanti sullo schermo e stampa solo un errore non intercettato nella console. Il secondo intercetta il rifiuto, lo memorizza, e il confine prende il controllo.

Dove mettere i confini

Un confine attorno all'intera app evita la schermata bianca, ma poi qualsiasi piccolo errore sostituisce tutto. Metti i confini attorno a parti che possono fallire in modo indipendente: un widget nella barra laterale, un grafico, ogni route. Un errore allora costa all'utente un pannello, non la pagina.

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

Solo il pannello Stocks mostra il suo fallback. Sposta entrambi i widget in un unico <ErrorBoundary> e il pannello Weather, che funziona, sparisce insieme a lui.

Senza alcun confine, React rimuove l'intero albero dallo schermo quando un errore di rendering non viene intercettato. Una pagina vuota è più sicura di una rotta che mostra dati sbagliati, ma gli utenti la leggono come un crash.

La libreria react-error-boundary

Il pacchetto react-error-boundary racchiude la classe per te e aggiunge funzioni per l'azzeramento. Non è disponibile in questo editor, quindi eccolo in un blocco statico:

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 azzera il confine quando cambia uno qualsiasi dei valori elencati, e showBoundary fa il trucco "memorizza e genera" dell'esempio precedente.

Segnalare gli errori in React 19

React 19 segnala gli errori in un modo nuovo. Gli errori intercettati da un confine vengono registrati una volta con console.error, e quelli non intercettati vanno a window.reportError. Per inviarli al tuo servizio, passa delle opzioni a createRoot. Ogni opzione sostituisce il corrispondente log predefinito:

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 è per gli errori che React ha sistemato senza il tuo aiuto, come un hydration mismatch o un errore di rendering sparito quando React ha riprovato. hydrateRoot accetta le stesse tre opzioni.

Errori comuni

Mettere il confine dentro il componente che genera l'errore. Un confine intercetta solo gli errori dei suoi figli. Se Profile renderizza <ErrorBoundary> attorno al proprio JSX e poi genera un errore nel proprio corpo, l'errore lo supera e arriva al confine successivo più in alto. Racchiudi il componente dal suo genitore.

Effetti collaterali in getDerivedStateFromError. Viene eseguito durante il rendering e può essere eseguito più di una volta, quindi limitati a restituire lo stato. I log vanno in componentDidCatch o nell'onCaughtError della root.

Un azzeramento che non sistema nulla. Azzerare l'errore del confine renderizza gli stessi figli con le stesse props. Se generano di nuovo un errore, l'utente torna al fallback. Prima cambia ciò che ha causato l'errore (recupera di nuovo i dati, elimina l'input errato, cambia la key), poi azzera l'errore, come fa il primo esempio con onReset.

Un solo confine per tutta l'app, e nient'altro. Evita la pagina vuota ma trasforma ogni piccolo guasto in un errore a tutta pagina. Aggiungi confini attorno alle funzionalità, e tieni quello al livello più alto come ultima risorsa.

Fallback che ti nascondono l'errore. Un messaggio cortese va bene per gli utenti, ma assicurati che l'errore arrivi comunque ai tuoi log. React 19 per default registra nella console gli errori intercettati; in produzione quella console è dell'utente, quindi invia gli errori a un servizio da componentDidCatch o da onCaughtError.

Gli error boundary si abbinano in modo naturale a <Suspense>: Suspense gestisce il "non ancora pronto", il confine gestisce il "fallito". Metti il confine fuori dal Suspense, come negli esempi con use, così un solo componente copre caricamento, successo e fallimento.