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.