Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / JavaScript

PromiseRejectionEvent.reason — a promise's rejection reason

PromiseRejectionEvent.reason exposes the rejection reason in unhandledrejection and rejectionhandled events. The property is read-only, but its value can be any JavaScript value, not just an Error object.

Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntax

event.reason
new PromiseRejectionEvent(type, { promise, reason })

PromiseRejectionEvent is a Web API interface inheriting from Event, not part of ECMAScript itself. The PromiseRejectionEvent.reason property, read as event.reason, contains the rejection reason. It can be a string, number, Error, another object, or undefined; therefore, do not assume that event.reason.message exists.

reason is read-only. In contrast, event.promise identifies the promise associated with the event: these properties represent the reason and the promise respectively, not two ways to read the same item.

unhandledrejection reports a rejection without an available rejection handler. rejectionhandled means a handler was attached later, after unhandledrejection had already been reported. Global listeners help with diagnostics but do not replace error handling with .catch() or try/catch around await.

The example constructs an event manually to demonstrate property access deterministically. The constructor's reason argument sets the value in this synthetic event; constructing the event neither rejects a promise nor dispatches the event. The immediate .catch() prevents a real unhandled rejection.

Run the example in a browser exposing PromiseRejectionEvent. This API is also available in Web Workers; the presence of Promise or the use of Node 24 does not establish support for this browser interface.

Examples

(() => {
  const reason = "TASK_FAILED";
  const promise = Promise.reject(reason);
  promise.catch(() => {});

  const event = new PromiseRejectionEvent("unhandledrejection", {
    promise,
    reason,
  });

  console.log(event.reason);
  console.log(event.promise === promise);
})();

Result

TASK_FAILED
true

The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.

Sources