Nuxt error.vue: Eigene Fehlerseiten gestalten

1. Wie Nuxt Laufzeitfehler automatisch weiterleitet

Wirft eine Seite, eine Middleware oder ein Server-Handler in Nuxt einen unbehandelten Fehler, fängt Nuxt diesen automatisch ab und wechselt in einen globalen Fehlerzustand. Statt der normalen Seite wird dann die Datei error.vue im Wurzelverzeichnis des Projekts gerendert, die als eine Art globaler Fallback für alle Fehlersituationen im gesamten Projekt dient.

Dieser Mechanismus greift sowohl für Fehler, die während des Server-Side Renderings auftreten, etwa ein fehlgeschlagener Datenbankzugriff in useAsyncData, als auch für Fehler, die erst später im Browser auftreten, etwa ein fehlgeschlagener API-Aufruf nach einer Nutzerinteraktion. In beiden Fällen erhält error.vue über eine eigene Prop Zugriff auf die Details des aufgetretenen Fehlers.

2. Die Struktur von error.vue

error.vue liegt direkt im Projekt-Root, auf derselben Ebene wie app.vue, und nicht im pages-Verzeichnis, da es sich um eine spezielle, von Nuxt reservierte Datei handelt. Die Komponente erhält den aufgetretenen Fehler als Prop namens error, welche unter anderem die Felder statusCode, statusMessage und message enthält.

Da error.vue außerhalb des normalen Layout-Systems gerendert wird, muss die Komponente ihr eigenes vollständiges HTML-Grundgerüst mitbringen, etwa eine eigene Kopf- und Fusszeile, falls diese auch auf der Fehlerseite sichtbar sein sollen. Ein bestehendes default.vue-Layout wird für die Fehlerseite nicht automatisch angewendet.

3. clearError() für Recovery-Aktionen

Der globale Fehlerzustand in Nuxt bleibt bestehen, bis er explizit wieder verlassen wird. Dafür stellt Nuxt die Funktion clearError() bereit, die den Fehlerzustand zurücksetzt und optional zu einer anderen Route weiterleitet. Ein typischer Anwendungsfall ist ein Button auf der Fehlerseite mit der Beschriftung Zurück zur Startseite, der beim Klick clearError() mit einer Zielroute aufruft.

Ohne den Aufruf von clearError() bliebe die Anwendung dauerhaft im Fehlerzustand hängen, selbst wenn der Nutzer versucht, über die Browser-Navigation zu einer funktionierenden Seite zu wechseln. Der explizite Reset ist deshalb ein notwendiger Bestandteil jeder sinnvoll gestalteten Fehlerseite und sollte nie vergessen werden.

<!-- error.vue -->
<template>
  <div class="error-page">
    <h1>{{ error.statusCode }}</h1>
    <p v-if="error.statusCode === 404">
      Diese Seite wurde leider nicht gefunden.
    </p>
    <p v-else>
      Etwas ist auf unserer Seite schiefgelaufen.
    </p>
    <button @click="handleRetry">Zurueck zur Startseite</button>
  </div>
</template>

<script setup lang="ts">
import type { NuxtError } from '#app';

const props = defineProps<{ error: NuxtError }>();

function handleRetry() {
  clearError({ redirect: '/' });
}
</script>

4. Unterschiedliche Darstellung je nach Statuscode

Da error.statusCode als reaktiver Wert innerhalb von error.vue zur Verfügung steht, lässt sich die Darstellung ohne zusätzlichen Aufwand an den jeweiligen Statuscode anpassen. Ein Statuscode 404 rechtfertigt in aller Regel einen freundlichen, wenig alarmierenden Text mit Vorschlägen zur Weiternavigation, während ein Statuscode 500 eher eine Entschuldigung sowie gegebenenfalls einen Hinweis auf eine automatische Fehlermeldung an das Entwicklungsteam verdient.

In der Praxis empfiehlt sich eine kleine Zuordnungstabelle oder ein switch-Statement innerhalb von error.vue, das für die häufigsten Statuscodes wie 404, 403 und 500 jeweils eine passende Überschrift, einen passenden Text und passende Handlungsempfehlungen liefert, anstatt für alle Fehler denselben generischen Text anzuzeigen.

5. Unterschied zwischen serverseitigen und clientseitigen Fehlern

Ein serverseitiger Fehler, etwa ein fehlgeschlagener Datenbankzugriff während des initialen Renderns, führt dazu, dass der Browser direkt die gerenderte error.vue-Seite mit dem entsprechenden HTTP-Statuscode erhält. Suchmaschinen und andere Crawler sehen in diesem Fall korrekt einen 404- oder 500-Statuscode in der HTTP-Antwort, was für SEO-Zwecke wichtig ist.

Ein clientseitiger Fehler, der erst nach der Hydration im Browser auftritt, etwa durch eine fehlgeschlagene Nutzeraktion, verändert dagegen nicht den ursprünglichen HTTP-Statuscode der Seite, da diese Antwort bereits längst abgeschlossen ist. Die Anwendung wechselt stattdessen im Client in den Fehlerzustand und zeigt error.vue als Overlay über der bestehenden Seite an, ohne dass ein erneuter Serveraufruf mit neuem Statuscode stattfindet.

6. Eigene Fehler gezielt werfen

Über die Funktion createError() lassen sich innerhalb von Seiten, Middleware oder Server-Handlern gezielt eigene Fehler mit einem selbst gewählten Statuscode und einer eigenen Nachricht erzeugen. Das ist besonders nützlich, wenn eine Ressource zwar technisch geladen werden konnte, inhaltlich aber nicht existiert, etwa ein Produkt mit einer ungültigen ID, das serverseitig als 404 behandelt werden soll.

Wird der optionale Parameter fatal: true an createError() übergeben, erzwingt Nuxt sofort den Wechsel in den globalen Fehlerzustand und das Rendering von error.vue, statt den Fehler lediglich als lokalen, in der Komponente behandelbaren Zustand zu behandeln. Ohne dieses Flag kann ein Fehler in bestimmten Kontexten auch lokal abgefangen werden, ohne die gesamte Seite zu ersetzen.

7. Layout und Styling der Fehlerseite

Da error.vue kein Layout aus dem layouts-Verzeichnis automatisch erhält, empfiehlt es sich, gemeinsame Bausteine wie Kopf- und Fusszeile als eigenständige, wiederverwendbare Komponenten auszulagern und sowohl im normalen Layout als auch direkt in error.vue einzubinden. So bleibt das Erscheinungsbild der Fehlerseite konsistent mit dem Rest der Anwendung, ohne Markup zu duplizieren.

Für Tailwind-basierte Projekte funktioniert das Styling innerhalb von error.vue genauso wie in jeder anderen Komponente, solange die globalen Styles korrekt eingebunden sind. Ein häufiger Fehler besteht darin, error.vue beim Testen der Fehlerseite zu übersehen und erst im produktiven Betrieb festzustellen, dass sie optisch nicht zum Rest der Anwendung passt. Ein kurzer manueller Test, etwa durch bewusstes Werfen eines Testfehlers in der Entwicklungsumgebung, gehört deshalb zu jeder Vorbereitung auf ein Deployment dazu.

8. showError() zum programmatischen Auslösen des Fehlerzustands

Neben createError(), das typischerweise zusammen mit einem throw verwendet wird, bietet Nuxt mit showError() eine Alternative, um den globalen Fehlerzustand direkt und ohne eine Exception auszulösen. Das ist etwa nützlich in einem globalen Fehlerhandler, der auf ein unbehandeltes Promise-Rejection-Ereignis reagiert und erst danach entscheidet, ob die gesamte Anwendung in den Fehlerzustand wechseln soll.

Während createError() primär ein Fehlerobjekt erzeugt, das anschließend geworfen wird, übernimmt showError() direkt den Wechsel in den globalen Zustand und das Rendern von error.vue. In der Praxis werden beide Funktionen häufig gemeinsam verwendet: createError() zur Erzeugung eines konsistenten Fehlerobjekts, showError() zur gezielten Aktivierung des Fehlerzustands außerhalb des regulären Rendering-Zyklus.

9. Fazit: Eine durchdachte Fehlerseite gehört zur Anwendung

Eine gut gestaltete error.vue ist mehr als nur eine technische Notwendigkeit, sie ist ein integraler Bestandteil der Nutzererfahrung, gerade in Momenten, in denen etwas schiefgelaufen ist. Statt der generischen Nuxt-Standardfehlerseite sollte jedes produktive Projekt eine eigene, markengerechte Fehlerseite mit klaren Handlungsempfehlungen und funktionierenden Recovery-Aktionen bereitstellen.

Wer clearError() konsequent einsetzt, die Darstellung je nach Statuscode anpasst und den Unterschied zwischen serverseitigen und clientseitigen Fehlern versteht, baut eine Fehlerseite, die Nutzer nicht im Stich lässt, sondern ihnen einen klaren Weg zurück zu einer funktionierenden Seite aufzeigt.

10. Zusammenfassung

11. FAQ: Nuxt error.vue: Das Wichtigste auf einen Blick