CKTIS / JavaScript
unhandledrejection — rejeição de Promise não tratada
O evento unhandledrejection assinala uma rejeição de Promise que continua sem tratamento quando o browser a comunica. Expõe a Promise e o motivo da rejeição; é útil para diagnóstico, mas não substitui o tratamento local de erros.
Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintaxe
window.addEventListener("unhandledrejection", (event) => { /* event.promise, event.reason */ });unhandledrejection é um evento da plataforma Web enviado para um objeto global, como window, sob a forma de PromiseRejectionEvent. Não é sintaxe ECMAScript. event.promise identifica a Promise rejeitada e event.reason contém o motivo da rejeição — qualquer valor, não necessariamente um objeto Error.
A notificação é assíncrona: o browser tem em conta os handlers adicionados durante o processamento de microtarefas e volta a verificar o estado do tratamento antes de enviar o evento. Assim, Promise.reject() por si só não garante um evento. Adicionar .catch() suficientemente cedo pode evitá-lo; adicionar um handler depois da comunicação pode provocar um evento separado rejectionhandled.
O evento é cancelável. event.preventDefault() suprime a comunicação predefinida na consola para essa rejeição, mas não altera o estado da Promise nem substitui .catch() ou try/catch em torno de await. Utilize-o com cuidado para não ocultar defeitos. Este mecanismo não é um registo completo de erros: o seguimento é omitido para scripts com a flag muted errors, incluindo alguns casos de scripts de origem cruzada.
O exemplo filtra os eventos pela identidade da Promise, regista o motivo e remove o listener. Execute-o como script numa página vazia do browser, não em Node.js. Esta API é especificada pelo HTML Living Standard; uma edição de ECMAScript ou a presença de Node 24 não comprova o suporte nos browsers.
Exemplos
(() => {
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
O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.