I built a small Node.js tool to detect unhandled promises

Manjeet Thakur — Sun, 14 Dec 2025 13:20:51 +0000

While working on Node.js projects, I kept running into a frustrating issue:
a Promise wasn’t awaited, nothing threw an error, but parts of the app behaved strangely or tests just hung.
After hitting this a few times, I decided to dig deeper and built a small tool to help me understand what was going on.
What I built
I created a small npm package called await-leak-detector.
Its goal is simple:
detect unhandled / floating Promises that can silently break async flows in Node.js.
At the moment, the tool only tracks Promises created using new Promise().
It does not yet support async/await or libraries like axios that return Promises — I’m actively working on extending it.
This started mainly as a learning and debugging experiment, not as a fully polished production-ready tool.
Why this exists
Unhandled promises can be tricky:
No error is thrown
No stack trace points to the problem
Tests may hang or behave inconsistently
I wanted something that could help surface these issues during development, even if it’s just a starting point.
Current limitations
Being transparent about this:
Only works for new Promise() right now
Doesn’t cover async functions yet
Not battle-tested in large production apps
But it’s already been useful for me while debugging async code.
What’s next
I’m currently working on:
Supporting async / await
Handling Promises returned by libraries like axios
Improving detection for real-world async patterns
Try it out
If you’ve faced issues with unhandled promises before, feel free to give it a try and share your feedback.
npm / repo:
👉 https://www.npmjs.com/package/await-leak-detector , https://github.com/Manjeet-singh-thakur/awaitly
Suggestions, issues, or PRs are very welcome 🙂

DEV Community: Manjeet Thakur

I built a small Node.js tool to detect unhandled promises