Navigation: navigateerror — Ereignis · JavaScript-Referenz

Signatur

navigation.addEventListener("navigateerror", handler)

Beschreibung

Das Ereignis navigateerror gehört zur Navigation API und wird am globalen Objekt window.navigation ausgelöst, wenn eine Navigation nicht erfolgreich abgeschlossen wird. Das Gegenstück ist navigatesuccess. Zusammen mit navigate bilden die beiden Ereignisse den Lebenszyklus einer Navigation in einer Single-Page-Application.

Typische Auslöser sind:

Der handler, der über NavigateEvent.intercept() übergeben wurde, gibt ein Promise zurück, das abgelehnt wird (z. B. weil ein fetch() fehlschlägt).
Die Navigation wird abgebrochen, etwa weil schon eine neue Navigation gestartet wurde, der Nutzer auf „Stopp“ klickt oder window.stop() aufgerufen wird. Dann ist event.error eine DOMException namens "AbortError".

Das Ereignisobjekt ist ein ErrorEvent. Die wichtigste Eigenschaft ist error. Sie enthält den eigentlichen Grund für das Scheitern. Außerdem gibt es message, filename, lineno und colno. Den Handler kannst du mit addEventListener("navigateerror", …) oder über die Eigenschaft navigation.onnavigateerror registrieren.

Das Ereignis eignet sich, um Ladeanzeigen zu entfernen, Fehlermeldungen anzuzeigen oder Fehler an ein Monitoring-System zu melden – und zwar an einer einzigen zentralen Stelle, egal welche Navigation fehlgeschlagen ist.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"navigateerror"`.
$handler Pflicht	(event: ErrorEvent) => void		Callback, der ein `ErrorEvent` erhält. Der Fehlergrund steht in `event.error`, die Fehlermeldung in `event.message`.
$options	boolean \| AddEventListenerOptions	false	Übliche Listener-Optionen wie `once` oder `signal`, mit denen sich der Listener automatisch entfernen lässt.

Rückgabewert

Typ

void

Beschreibung

addEventListener() gibt nichts zurück. Der Handler erhält ein ErrorEvent.

Beispiele

Zentrale Fehlerbehandlung für SPA-Navigationen

const spinner = document.querySelector('#spinner');

navigation.addEventListener('navigate', (event) => {
  if (!event.canIntercept) return;
  const url = new URL(event.destination.url);
  if (!url.pathname.startsWith('/artikel/')) return;

  event.intercept({
    async handler() {
      spinner.hidden = false;
      const res = await fetch(`/api${url.pathname}`);
      if (!res.ok) throw new Error(`HTTP ${res.status}`);
      document.querySelector('main').textContent = await res.text();
    }
  });
});

navigation.addEventListener('navigatesuccess', () => {
  spinner.hidden = true;
});

navigation.addEventListener('navigateerror', (event) => {
  spinner.hidden = true;
  console.error('Navigation fehlgeschlagen:', event.message);
});

Navigation fehlgeschlagen: Uncaught Error: HTTP 404

Abbrüche von echten Fehlern unterscheiden

navigation.addEventListener('navigateerror', (event) => {
  const { error } = event;
  if (error instanceof DOMException && error.name === 'AbortError') {
    // Nutzer hat neu navigiert oder gestoppt – kein echter Fehler
    console.info('Navigation abgebrochen');
    return;
  }
  // Echte Fehler an ein Monitoring melden
  navigator.sendBeacon('/log', JSON.stringify({
    url: location.href,
    message: String(error?.message ?? event.message)
  }));
});

Navigation abgebrochen

Über onnavigateerror registrieren und wieder entfernen

// Variante 1: Event-Handler-Eigenschaft (ersetzt einen früheren Handler)
navigation.onnavigateerror = (event) => {
  console.warn('Fehler:', event.error);
};

// Wieder entfernen
navigation.onnavigateerror = null;

// Variante 2: benannter Listener mit removeEventListener
const onError = (event) => console.warn('Fehler:', event.error);
navigation.addEventListener('navigateerror', onError);
// ... später
navigation.removeEventListener('navigateerror', onError);

Alternative: Promise von navigate() auswerten

const zeigeSeite = async (pfad) => {
  const { finished } = navigation.navigate(pfad);
  try {
    await finished;
    console.log('Fertig:', pfad);
  } catch (err) {
    // Wird zusätzlich zum navigateerror-Ereignis abgelehnt
    console.log('Fehlgeschlagen:', err.name);
  }
};

zeigeSeite('/artikel/42');

Fehlgeschlagen: Error

// Wichtig · Fallstricke

Browser-Kompatibilität: Die Navigation API gibt es in Chromium-Browsern ab Version 102. Firefox und Safari unterstützen sie erst seit kurzem. Prüfe deshalb vorher mit if ('navigation' in window) und plane für ältere Browser einen Fallback über die History API (popstate) ein.
AbortError ist normal: Klickt der Nutzer schnell hintereinander auf Links, wird die vorherige Navigation abgebrochen und navigateerror mit einem AbortError ausgelöst. Filtere diese Fälle heraus, sonst zeigst du unnötige Fehlermeldungen an oder füllst dein Log.
Die URL ist zum Zeitpunkt des Fehlers meist schon festgeschrieben: Bei abgefangenen Navigationen ändert sich die Adresszeile vor dem Ausführen des Handlers. Bei einem Fehler musst du also selbst eine Fehleransicht anzeigen oder zurücknavigieren.
Das Ereignis wird nur für Navigationen im aktuellen Dokument ausgelöst. Schlägt ein vollständiger Seitenwechsel fehl (z. B. ein Netzwerkfehler bei einer nicht abgefangenen Navigation), wird es nicht ausgelöst.
Mit navigation.onnavigateerror = … ist immer nur ein Handler aktiv. Für mehrere unabhängige Listener nimm addEventListener.
Das Ereignis ist nicht abbrechbar. preventDefault() hat keine Wirkung.

Siehe auch

Navigation NavigateEvent.prototype.intercept() Navigation.prototype.navigate() Navigation.transition ErrorEvent