Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

unhandledrejection — rifiuto di promise non gestito

L’evento unhandledrejection segnala un rifiuto di Promise che non è stato gestito quando il browser lo notifica. Espone la promise e il motivo del rifiuto; è utile per la diagnostica, ma non sostituisce la gestione locale degli errori.

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

Sintassi

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

unhandledrejection è un evento della piattaforma Web inviato a un oggetto globale, come window, sotto forma di PromiseRejectionEvent. Non è sintassi ECMAScript. event.promise identifica la promise rifiutata e event.reason contiene il motivo del rifiuto — un valore qualsiasi, non necessariamente un oggetto Error.

La notifica è asincrona: il browser tiene conto dei gestori aggiunti durante l’elaborazione delle microtask e ricontrolla lo stato della gestione prima di inviare l’evento. Di conseguenza, Promise.reject() da solo non garantisce un evento. Aggiungere .catch() abbastanza presto può impedirlo; aggiungere un gestore dopo la notifica può causare un evento separato rejectionhandled.

L’evento è annullabile. event.preventDefault() sopprime la segnalazione predefinita nella console per quel rifiuto, ma non modifica lo stato della promise né sostituisce .catch() o try/catch attorno a await. Usalo consapevolmente per evitare di nascondere difetti. Questo meccanismo non è un registro completo degli errori: il tracciamento viene omesso per gli script con il flag muted errors, compresi alcuni casi di script cross-origin.

L’esempio filtra gli eventi in base all’identità della promise, registra il motivo e rimuove il listener. Eseguilo come script in una pagina vuota del browser, non in Node.js. Questa API è specificata dall’HTML Living Standard; un’edizione ECMAScript o la presenza di Node 24 non dimostrano il supporto nei browser.

Esempi

(() => {
  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");
})();

Risultato

unhandled: demo

Il codice mostrato e il risultato dichiarato sono stati verificati in un ambiente isolato con il metodo registrato nella prova di verifica di questa versione esatta.

Fonti