PromiseRejectionEvent.reason — Eigenschaft · JavaScript-Referenz

Signatur

PromiseRejectionEvent.reason

Beschreibung

Die Eigenschaft reason eines PromiseRejectionEvent liefert genau den Wert, der beim Zurückweisen eines Promise übergeben wurde. Das ist z. B. das Argument von Promise.reject(wert), der Wert beim Aufruf von reject(wert) im Promise-Konstruktor oder eine Ausnahme, die in einer async-Funktion bzw. einem .then()-Callback geworfen wurde.

Man braucht die Eigenschaft vor allem in globalen Handlern für die Events unhandledrejection und rejectionhandled. Dort können Sie nicht behandelte Promise-Fehler zentral protokollieren, an ein Fehler-Monitoring (z. B. Sentry oder einen eigenen Endpunkt) senden oder dem Nutzer eine Meldung anzeigen.

Weil JavaScript erlaubt, jeden Wert zurückzuweisen, ist reason vom Typ any. Es kann ein Error mit message und stack sein, aber auch ein String, eine Zahl, ein einfaches Objekt oder undefined. Robuster Code prüft deshalb vor der Auswertung, z. B. mit reason instanceof Error.

Rückgabewert

Typ

any

Beschreibung

Der Grund der Zurückweisung – der Wert, der an reject() bzw. Promise.reject() übergeben oder in einer asynchronen Kette geworfen wurde. Kann auch undefined sein.

Beispiele

Nicht behandelte Zurückweisungen global protokollieren

window.addEventListener("unhandledrejection", (event) => {
  const { reason } = event;
  if (reason instanceof Error) {
    console.error("Unbehandelter Fehler:", reason.message);
  } else {
    console.error("Unbehandelte Zurückweisung mit Wert:", reason);
  }
});

// Löst das Event aus, da kein .catch() vorhanden ist
Promise.reject(new Error("Verbindung fehlgeschlagen"));

Unbehandelter Fehler: Verbindung fehlgeschlagen

Fehler an ein Monitoring-Backend senden

const serialisiereGrund = (reason) =>
  reason instanceof Error
    ? { name: reason.name, message: reason.message, stack: reason.stack }
    : { wert: String(reason) };

window.onunhandledrejection = (event) => {
  navigator.sendBeacon(
    "/api/fehler",
    JSON.stringify({ typ: "unhandledrejection", ...serialisiereGrund(event.reason) })
  );
  // Standard-Konsolenausgabe des Browsers unterdrücken
  event.preventDefault();
};

const ladeDaten = async () => {
  const res = await fetch("/gibt-es-nicht");
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
};
ladeDaten(); // kein await, kein catch

Nicht-Error-Werte und rejectionhandled

window.addEventListener("unhandledrejection", (e) => {
  console.log("unbehandelt:", typeof e.reason, e.reason);
});
window.addEventListener("rejectionhandled", (e) => {
  console.log("nachträglich behandelt:", e.reason);
});

const p = Promise.reject({ code: 42 });

// Später doch noch behandeln -> löst rejectionhandled aus
setTimeout(() => p.catch(() => {}), 1000);

unbehandelt: object { code: 42 } nachträglich behandelt: { code: 42 }

Eigenes Event konstruieren (z. B. für Tests)

const promise = Promise.reject("Timeout");
promise.catch(() => {}); // echte Zurückweisung abfangen

const event = new PromiseRejectionEvent("unhandledrejection", {
  promise,
  reason: "Timeout",
  cancelable: true
});

console.log(event.reason);

Timeout

// Wichtig · Fallstricke

Beliebiger Typ: reason ist nicht zwingend ein Error. Zugriffe wie reason.message oder reason.stack können undefined liefern oder bei reason === null sogar einen TypeError auslösen. Prüfen Sie den Typ vorher.
Schreibgeschützt: Eine Zuweisung an event.reason hat keine Wirkung (im Strict Mode gibt es einen TypeError). Den Wert legen Sie nur beim Konstruktor über init.reason fest.
Serialisierung: JSON.stringify(new Error(\"x\")) ergibt {}, weil message und stack nicht aufzählbar sind. Übernehmen Sie die Felder beim Versenden von Fehlerberichten ausdrücklich.
Sicherheit/Datenschutz: reason kann sensible Daten enthalten (URLs mit Token, Serverantworten). Filtern Sie diese, bevor Sie sie an externe Dienste senden.
Kompatibilität: In allen modernen Browsern und in Web Workern verfügbar; Firefox erst ab Version 69. Node.js kennt kein PromiseRejectionEvent, sondern process.on(\"unhandledRejection\", (reason, promise) => …). Hier wird der Grund direkt als erstes Argument übergeben.

Siehe auch

PromiseRejectionEvent PromiseRejectionEvent.promise Promise.reject() Promise.prototype.catch() DeviceOrientationEvent.beta