error.js

Un fichier error définit une limite d'erreur (error boundary) pour un segment de route.

Il est utile pour intercepter les erreurs inattendues qui surviennent dans les composants serveur et client, et afficher une interface de repli (fallback UI).

'use client' // Les composants d'erreur doivent être des composants client

import { useEffect } from 'react'

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  useEffect(() => {
    // Enregistrer l'erreur dans un service de suivi
    console.error(error)
  }, [error])

  return (
    <div>
      <h2>Quelque chose s'est mal passé !</h2>
      <button
        onClick={
          // Tenter de récupérer en re-rendant le segment
          () => reset()
        }
      >
        Réessayer
      </button>
    </div>
  )
}
'use client' // Les composants d'erreur doivent être des composants client

import { useEffect } from 'react'

export default function Error({ error, reset }) {
  useEffect(() => {
    // Enregistrer l'erreur dans un service de suivi
    console.error(error)
  }, [error])

  return (
    <div>
      <h2>Quelque chose s'est mal passé !</h2>
      <button
        onClick={
          // Tenter de récupérer en re-rendant le segment
          () => reset()
        }
      >
        Réessayer
      </button>
    </div>
  )
}

Props

error

Une instance d'un objet Error transmise au composant client error.js.

error.message

Le message d'erreur.

  • Pour les erreurs provenant de composants client, ce sera le message d'origine de l'erreur.
  • Pour les erreurs provenant de composants serveur, ce sera un message générique pour éviter de divulguer des détails sensibles. error.digest peut être utilisé pour faire correspondre l'erreur dans les logs côté serveur.

error.digest

Un hachage généré automatiquement pour l'erreur levée dans un composant serveur. Peut être utilisé pour faire correspondre l'erreur dans les logs côté serveur.

reset

Une fonction pour réinitialiser la limite d'erreur (error boundary). Lorsqu'elle est exécutée, la fonction tentera de re-rendre le contenu de la limite d'erreur. Si réussie, le composant de repli est remplacé par le résultat du nouveau rendu.

Peut être utilisé pour inciter l'utilisateur à tenter de récupérer de l'erreur.

Bon à savoir :

  • Les limites error.js doivent être des composants client.
  • Dans les builds de production, les erreurs provenant des composants serveur seront dépouillées de leurs détails spécifiques pour éviter de divulguer des informations sensibles.
  • Une limite error.js ne gérera pas les erreurs levées dans un composant layout.js du même segment car la limite d'erreur est imbriquée à l'intérieur de ce composant de mise en page.
    • Pour gérer les erreurs d'une mise en page spécifique, placez un fichier error.js dans le segment parent de la mise en page.
    • Pour gérer les erreurs dans la mise en page racine ou le template, utilisez une variante de error.js appelée app/global-error.js.

global-error.js

Pour gérer spécifiquement les erreurs dans le layout.js racine, utilisez une variante de error.js appelée app/global-error.js située dans le répertoire racine app.

'use client'

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <html>
      <body>
        <h2>Quelque chose s'est mal passé !</h2>
        <button onClick={() => reset()}>Réessayer</button>
      </body>
    </html>
  )
}
'use client'

export default function GlobalError({ error, reset }) {
  return (
    <html>
      <body>
        <h2>Quelque chose s'est mal passé !</h2>
        <button onClick={() => reset()}>Réessayer</button>
      </body>
    </html>
  )
}

Bon à savoir :

  • global-error.js remplace le layout.js racine lorsqu'il est actif et doit donc définir ses propres balises <html> et <body>.
  • Lors de la conception d'interfaces d'erreur, vous pouvez trouver utile d'utiliser les React Developer Tools pour basculer manuellement entre les limites d'erreur.

not-found.js

Le fichier not-found est utilisé pour afficher une interface lorsque la fonction notFound() est appelée dans un segment de route.

Historique des versions

VersionChangements
v13.1.0Introduction de global-error.
v13.0.0Introduction de error.