Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

unhandledrejection — rejet de promesse non traité

L’événement unhandledrejection signale un rejet de Promise qui n’a pas été traité au moment où le navigateur le signale. Il expose la promesse et la raison du rejet ; il sert au diagnostic et ne remplace pas la gestion locale des erreurs.

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

Syntaxe

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

unhandledrejection est un événement de la plateforme Web envoyé à un objet global, tel que window, sous la forme d’un PromiseRejectionEvent. Ce n’est pas de la syntaxe ECMAScript. event.promise désigne la promesse rejetée et event.reason contient la raison du rejet — n’importe quelle valeur, pas nécessairement un objet Error.

La notification est asynchrone : le navigateur tient compte des gestionnaires ajoutés pendant le traitement des microtâches et vérifie à nouveau l’état de traitement avant de distribuer l’événement. Par conséquent, Promise.reject() seul ne garantit pas l’émission d’un événement. Ajouter .catch() assez tôt peut l’empêcher ; ajouter un gestionnaire après le signalement peut provoquer un événement distinct rejectionhandled.

L’événement est annulable. event.preventDefault() supprime le signalement par défaut de ce rejet dans la console, mais ne modifie pas l’état de la promesse et ne remplace pas .catch() ni try/catch autour de await. Utilisez-le avec discernement pour éviter de masquer des défauts. Ce mécanisme ne constitue pas un journal complet des erreurs : le suivi est ignoré pour les scripts ayant le marqueur muted errors, notamment dans certains cas de scripts cross-origin.

L’exemple filtre les événements selon l’identité de la promesse, affiche la raison et supprime son écouteur. Exécutez-le comme script dans une page de navigateur vide, et non dans Node.js. Cette API est spécifiée par le HTML Living Standard ; une édition d’ECMAScript ou la présence de Node 24 ne prouve pas la prise en charge par un navigateur.

Exemples

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

Résultat

unhandled: demo

Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.

Sources