Window: rejectionhandled — Ereignis · JavaScript-Referenz

Signatur

window.addEventListener("rejectionhandled", handler)

Beschreibung

Das Ereignis rejectionhandled ist das Gegenstück zu unhandledrejection. Wird ein Promise abgelehnt und hat es zu diesem Zeitpunkt noch keinen Ablehnungs-Handler (.catch(), zweites Argument von .then() oder await in try/catch), meldet der Browser zuerst unhandledrejection. Bekommt dasselbe Promise später doch noch einen Handler, folgt rejectionhandled.

Das Ereignis ist vom Typ PromiseRejectionEvent und hat zwei wichtige Eigenschaften: promise (das betroffene Promise) und reason (der Ablehnungsgrund). Es lässt sich nicht abbrechen und steigt nicht auf (kein Bubbling). Den Handler registrieren Sie entweder mit window.addEventListener("rejectionhandled", handler) oder über die Eigenschaft window.onrejectionhandled. In Workern funktioniert das genauso über self.

In der Praxis braucht man das Ereignis vor allem für Fehler-Tracking und Telemetrie. Ein Werkzeug merkt sich bei unhandledrejection alle Promises, die bisher unbehandelt sind. Kommt rejectionhandled, nimmt es das Promise wieder aus der Liste. So werden nur Ablehnungen gemeldet, die wirklich nie behandelt werden. Fehlalarme durch verspätete Handler fallen weg.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"rejectionhandled"`.
$handler Pflicht	(event: PromiseRejectionEvent) => void		Callback-Funktion. Sie bekommt ein `PromiseRejectionEvent` mit den Eigenschaften `promise` und `reason`.
$options	boolean \| AddEventListenerOptions	false	Optionale Einstellungen wie `once` oder `signal`. `capture` spielt keine Rolle, weil das Ereignis direkt am globalen Objekt ausgelöst wird.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Rückgabewert des Handlers wird ignoriert.

Beispiele

Verspätete Behandlung mit addEventListener erkennen

window.addEventListener('unhandledrejection', (event) => {
  console.log('Unbehandelt:', event.reason.message);
});

window.addEventListener('rejectionhandled', (event) => {
  console.log('Nachträglich behandelt:', event.reason.message);
});

const p = Promise.reject(new Error('Timeout'));

// Der Handler kommt erst später dazu
setTimeout(() => {
  p.catch(() => {});
}, 1000);

Unbehandelt: Timeout Nachträglich behandelt: Timeout

Fehler-Tracking ohne Fehlalarme

const pending = new Map();

window.addEventListener('unhandledrejection', (event) => {
  pending.set(event.promise, event.reason);
});

window.addEventListener('rejectionhandled', (event) => {
  pending.delete(event.promise);
});

// Alle 5 Sekunden nur die wirklich unbehandelten Ablehnungen melden
setInterval(() => {
  for (const [promise, reason] of pending) {
    console.warn('Melde an Server:', String(reason));
    pending.delete(promise);
  }
}, 5000);

Über die on-Property und im Web Worker

// Im Hauptthread: nur ein einziger Handler möglich
window.onrejectionhandled = (event) => {
  console.log('Promise wurde behandelt:', event.promise);
};

// Handler wieder entfernen
// window.onrejectionhandled = null;

// In worker.js: dieselbe API über self
self.addEventListener('rejectionhandled', (event) => {
  self.postMessage({ type: 'handled', reason: String(event.reason) });
});

Promise wurde behandelt: Promise {<rejected>: ...}

// Wichtig · Fallstricke

rejectionhandled kommt nur, wenn für dasselbe Promise vorher ein unhandledrejection-Ereignis ausgelöst wurde. Bekommt ein Promise seinen Handler noch in derselben Microtask-Phase, entstehen keine Ereignisse.
Wenn Sie Promises in einer Map sammeln, hält das die Objekte im Speicher. Räumen Sie die Einträge regelmäßig auf, sonst entstehen Speicherlecks.
Das Ereignis lässt sich nicht abbrechen. preventDefault() bewirkt nichts. Die Konsolenwarnung zu unbehandelten Ablehnungen unterdrücken Sie mit preventDefault() nur im unhandledrejection-Handler.
Browser: in allen modernen Browsern verfügbar, Firefox erst ab Version 69. In Node.js gibt es stattdessen process.on('rejectionHandled', ...) (mit großem H).
Ablehnungsgründe können sensible Daten enthalten. Senden Sie reason nicht ungefiltert an externe Tracking-Dienste.

Siehe auch

Window: unhandledrejection Promise Promise.prototype.catch() Window: error IDBTransaction: abort