Handling Rejection - Tales From The Event Loop Ep. 2

David N. Booth

Scuba Equipment - Tools for Diving In

• If a Promise rejects without any rejection handlers registered, nothing happens. There are, after all, no rejection handlers registered. The host environment totally knows though. It's watching you. ¹
• At the end of a turn of the event loop, if a Promise rejected during that turn without ever having a rejection handler registered, the host environment makes a big fuss.
• If you register a rejection handler for a Promise which rejected on a previous turn of the event loop (and was never handled) it is considered to be "handled late". In response, the host environment emits a 'rejectionHandled' event.
• await is a rejection handler. An await-ed Promise will never have an unhandled rejection. ^{2 3}

Two roads diverged in a wood, and I—
I took the one traveled by NodeJS
- Robert Frost, early draft of The Road Not Taken (maybe)

Code Examples

Diving Practice - In the Swimming Pool

(async () => {
    Promise.reject("Rejected!");
})();

(async () => {
    try {
        Promise.reject("Rejected!");
    } catch {
        console.log("Caught!");
    }
})();

(async () => {
    Promise.reject("Rejected!");
})().catch(() => { console.log("Caught!") });

(async () => {
    await Promise.reject("Rejected!");
})();

(async () => {
    try {
        await Promise.reject("Rejected!");
    } catch {
        console.log("Caught!");
    }
})();

(async () => {
    await Promise.reject("Rejected!");
})().catch(() => { console.log("Caught!") });

Diving Deeper

Level 1 - Register the handler during the event loop turn

(async () => {
    const p = Promise.reject("Rejected!");
    queueMicrotask(() => {
        p.catch(() => { console.log("Caught!") });
    });
})();

Level 2 - Register the handler during a task before the unhandledRejection event

window.onunhandledrejection = () => { console.log("unhandledRejection") };
window.onrejectionhandled = () => { console.log("rejectionHandled") };
(async () => {
    const p = Promise.reject("Rejected!");
    setTimeout(() => {
        p.catch(() => { console.log("Caught!") });
        },
        0
    );
})();

Level 4 - Register the handler during a task after the unhandledRejection event

window.onunhandledrejection = () => { console.log("unhandledRejection") };
window.onrejectionhandled = () => { console.log("rejectionHandled") };
(async () => {
    const p = Promise.reject("Rejected!");
    setTimeout(() => {
        p.catch(() => { console.log("Caught!") });
        },
        5000
    );
})();

window.onunhandledrejection = () => { console.log("unhandledRejection") };
window.onrejectionhandled = () => { console.log("rejectionHandled") };
(async () => {
    const p = Promise.reject("Rejected!");
    setTimeout(async () => {
        await p;
        },
        5000
    );
})();

Level 3 - Register the handler during the unhandledRejection event

let p;
window.onunhandledrejection = () => {
    console.log("unhandledRejection");
    p.catch(() => { console.log("Caught!") });
};
window.onrejectionhandled = () => { console.log("rejectionHandled") };
(async () => {
    p = Promise.reject("Rejected!");
})();

let p;
window.onunhandledrejection = (e) => {
    console.log("unhandledRejection");
    p.catch(() => { console.log("Caught!") });
    e.preventDefault();
};
window.onrejectionhandled = () => { console.log("rejectionHandled") };
(async () => {
    p = Promise.reject("Rejected!");
})();

Takeaways

Footnotes

1 Promise rejections are tracked behind the scenes with a HostPromiseRejectionTracker. ↩

2 Unless you await it much later than when it first rejected, but please don't do that unless you're writing a blog post. ↩

3 .catch(), .then() (with the second argument), Promise.allSettled, and the rest of the Promise aggregating methods (any, all, etc.) also register rejection handlers. ↩

4 Examples in this article were tested with: Edge/Chrome v145, Firefox v148, and Safari v17.4 ↩

5 Examples in this article were tested with Node v22.21.1, Bun v1.3.10, and Deno 2.7.3, but I only discuss Node in the text because I found the clearest documentation for it. ↩

6 As of Node v15. See "History" on --unhandled-rejections ↩

7 This doesn't actually kill the program, but the error will unless you catch it, e.g. with process.on('uncaughtException') ↩

8 The REPL for Node, Bun, or Deno is like this too. This is useful for running code snippets and doing terrible things like writing articles about JavaScript, but we won't include it in the discussion here because it isn't how anyone is running production JS code. ↩

9 This isn't necessarily a bad thing. This article is not saying that you should go add process.on('unhandledRejection') handlers to all your Node scripts. It is often useful for your program to be killed if something unexpected happens. ↩

10 Like maybe a fast-drying wood glue, nothing too tedious. ↩

11 In Node, Bun, or Deno, we replace the window.oneventname = callback lines with process.on("eventName", callback). ↩

12 The answers for Firefox and Safari include the error message that the browser printed out for the unhandled rejection. In the server environments, we don't see this message because the global event listener is handling the rejection. The Chromium browsers are more exciting. I see the message but then it gets erased when the rejectionHandled fires! Try it yourself right now. What a rush. ↩

13 You can also try this exercise with Promise.all, Promise.allSettled, Promise.any, and Promise.race to prove that these all also count as rejection handlers. ↩

14 This is my interpretation based on this experiment. I have no idea if this behaviour is defined in any spec or if it is subject to change. If you ever find yourself writing code which relies on this behaviour, it might be time to rethink some of the choices you've made. ↩

15 This is browser-only. In Node, the arguments passed to the listener don't include an Event object with a preventDefault method. ↩