Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / JavaScript

unhandledrejection — rechazo de promesa no gestionado

El evento unhandledrejection informa de un rechazo de Promise que sigue sin gestionarse cuando el navegador lo notifica. Expone la promesa y el motivo del rechazo; sirve para el diagnóstico, no para sustituir la gestión local de errores.

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

Sintaxis

window.addEventListener("unhandledrejection", (event) => { /* event.promise, event.reason */ });

unhandledrejection es un evento de la plataforma Web que se envía a un objeto global, como window, en forma de PromiseRejectionEvent. No es sintaxis de ECMAScript. event.promise identifica la promesa rechazada y event.reason contiene el motivo del rechazo: cualquier valor, no necesariamente un objeto Error.

La notificación es asíncrona: el navegador tiene en cuenta los manejadores añadidos durante el procesamiento de microtareas y vuelve a comprobar el estado de gestión antes de enviar el evento. Por tanto, Promise.reject() por sí solo no garantiza que se produzca un evento. Añadir .catch() con suficiente antelación puede evitarlo; añadir un manejador después de la notificación puede provocar un evento distinto, rejectionhandled.

El evento se puede cancelar. event.preventDefault() suprime el informe predeterminado en la consola para ese rechazo, pero no cambia el estado de la promesa ni sustituye a .catch() o a try/catch alrededor de await. Úsalo con cuidado para no ocultar defectos. Este mecanismo no es un registro completo de errores: se omite el seguimiento de los scripts con la marca muted errors, incluidos algunos casos de scripts de origen cruzado.

El ejemplo filtra los eventos según la identidad de la promesa, registra el motivo y elimina el listener. Ejecútalo como un script en una página vacía del navegador, no en Node.js. Esta API está especificada por el HTML Living Standard; una edición de ECMAScript o la presencia de Node 24 no demuestra que sea compatible con los navegadores.

Ejemplos

(() => {
  let rejected;

  function report(event) {
    if (event.promise !== rejected) return;
    event.preventDefault();
    window.removeEventListener("unhandledrejection", report);
    console.log("unhandled:", event.reason);
  }

  window.addEventListener("unhandledrejection", report);
  rejected = Promise.reject("demo");
})();

Resultado

unhandled: demo

El código mostrado y el resultado declarado se verificaron en un entorno aislado mediante el método registrado en la evidencia de verificación de esta versión exacta.

Fuentes