Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

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.

Fontes