error.js

Eine error-Datei ermöglicht es Ihnen, unerwartete Laufzeitfehler abzufangen und eine Fallback-UI anzuzeigen.

'use client' // Error Boundaries müssen Client Components sein

import { useEffect } from 'react'

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  useEffect(() => {
    // Fehler an einen Error Reporting Service senden
    console.error(error)
  }, [error])

  return (
    <div>
      <h2>Etwas ist schiefgelaufen!</h2>
      <button
        onClick={
          // Versuch, durch erneutes Rendern des Segments wiederherzustellen
          () => reset()
        }
      >
        Erneut versuchen
      </button>
    </div>
  )
}

error.js umschließt ein Routensegment und seine verschachtelten Kinder in einem React Error Boundary. Wenn innerhalb des Boundaries ein Fehler auftritt, wird die error-Komponente als Fallback-UI angezeigt.

Wichtig zu wissen:

Mit den React DevTools können Sie Error Boundaries ein- und ausschalten, um Fehlerzustände zu testen.

Wenn Sie möchten, dass Fehler an das übergeordnete Error Boundary weitergegeben werden, können Sie throw beim Rendern der error-Komponente verwenden.

Referenz

Props

`error`

Eine Instanz eines Error-Objekts, das an die error.js Client Component weitergegeben wird.

Wichtig zu wissen: Während der Entwicklung wird das Error-Objekt, das an den Client weitergegeben wird, serialisiert und enthält die message des ursprünglichen Fehlers zur einfacheren Fehlersuche. In der Produktion ist dieses Verhalten jedoch anders, um potenziell sensible Details, die im Fehler enthalten sein könnten, nicht an den Client zu übermitteln.

`error.message`

Fehler, die von Client Components weitergegeben werden, zeigen die ursprüngliche Error-Nachricht.
Fehler, die von Server Components weitergegeben werden, zeigen eine generische Nachricht mit einem Identifikator. Dies dient dazu, sensible Details nicht preiszugeben. Der Identifikator unter errors.digest kann verwendet werden, um die entsprechenden serverseitigen Logs zuzuordnen.

`error.digest`

Ein automatisch generierter Hash des aufgetretenen Fehlers. Er kann verwendet werden, um den entsprechenden Fehler in serverseitigen Logs zu finden.

`reset`

Die Ursache eines Fehlers kann manchmal temporär sein. In diesen Fällen kann ein erneuter Versuch das Problem beheben.

Eine Fehlerkomponente kann die Funktion reset() verwenden, um den Benutzer aufzufordern, den Fehler zu beheben. Bei Ausführung versucht die Funktion, die Inhalte des Error Boundaries erneut zu rendern. Wenn dies erfolgreich ist, wird die Fallback-Fehlerkomponente durch das Ergebnis des erneuten Renderings ersetzt.

'use client' // Error Boundaries müssen Client Components sein

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <div>
      <h2>Etwas ist schiefgelaufen!</h2>
      <button onClick={() => reset()}>Erneut versuchen</button>
    </div>
  )
}

Beispiele

Globaler Fehler

Weniger häufig, aber möglich, ist die Behandlung von Fehlern im Root-Layout oder Template mit global-error.js, das sich im Root-App-Verzeichnis befindet, auch bei Verwendung von Internationalisierung. Die globale Fehler-UI muss ihre eigenen <html>- und <body>-Tags definieren. Diese Datei ersetzt das Root-Layout oder Template, wenn sie aktiv ist.

'use client' // Error Boundaries müssen Client Components sein

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    // global-error muss html- und body-Tags enthalten
    <html>
      <body>
        <h2>Etwas ist schiefgelaufen!</h2>
        <button onClick={() => reset()}>Erneut versuchen</button>
      </body>
    </html>
  )
}

Anmutige Fehlerbehebung mit einem benutzerdefinierten Error Boundary

Wenn das Rendering auf dem Client fehlschlägt, kann es nützlich sein, die letzte bekannte serverseitig gerenderte UI anzuzeigen, um eine bessere Benutzererfahrung zu bieten.

Das GracefullyDegradingErrorBoundary ist ein Beispiel für ein benutzerdefiniertes Error Boundary, das das aktuelle HTML vor einem Fehler erfasst und speichert. Tritt ein Rendering-Fehler auf, wird das erfasste HTML erneut gerendert und eine persistente Benachrichtigungsleiste angezeigt, um den Benutzer zu informieren.

'use client'

import React, { Component, ErrorInfo, ReactNode } from 'react'

interface ErrorBoundaryProps {
  children: ReactNode
  onError?: (error: Error, errorInfo: ErrorInfo) => void
}

interface ErrorBoundaryState {
  hasError: boolean
}

export class GracefullyDegradingErrorBoundary extends Component<
  ErrorBoundaryProps,
  ErrorBoundaryState
> {
  private contentRef: React.RefObject<HTMLDivElement>

  constructor(props: ErrorBoundaryProps) {
    super(props)
    this.state = { hasError: false }
    this.contentRef = React.createRef()
  }

  static getDerivedStateFromError(_: Error): ErrorBoundaryState {
    return { hasError: true }
  }

  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
    if (this.props.onError) {
      this.props.onError(error, errorInfo)
    }
  }

  render() {
    if (this.state.hasError) {
      // Aktuellen HTML-Inhalt ohne Hydration rendern
      return (
        <>
          <div
            ref={this.contentRef}
            suppressHydrationWarning
            dangerouslySetInnerHTML={{
              __html: this.contentRef.current?.innerHTML || '',
            }}
          />
          <div className="fixed bottom-0 left-0 right-0 bg-red-600 text-white py-4 px-6 text-center">
            <p className="font-semibold">
              Beim Rendern der Seite ist ein Fehler aufgetreten
            </p>
          </div>
        </>
      )
    }

    return <div ref={this.contentRef}>{this.props.children}</div>
  }
}

export default GracefullyDegradingErrorBoundary

Versionsverlauf

Version	Änderungen
`v15.2.0`	Zeigt `global-error` auch in der Entwicklung.
`v13.1.0`	`global-error` eingeführt.
`v13.0.0`	`error` eingeführt.

Fehlerbehandlung

Erfahren Sie, wie Sie erwartete Fehler anzeigen und unbehandelte Ausnahmen verwalten können.

Fehlerbehandlung

On this page