What does UnhandledPromiseRejectionWarning mean in Node.js?
What triggers the warning
A Promise rejection is considered 'unhandled' when the Promise is rejected and no rejection handler is attached to it by the time the microtask queue finishes. This commonly happens with async functions that throw, or with .then() chains that lack a .catch().
Node.js emits UnhandledPromiseRejectionWarning to the console and, in newer versions, may also print a deprecation warning. Since Node.js 15, the default behavior is to terminate the process with a non-zero exit code, so ignoring it can crash your app.
- Calling an async function without await or .catch()
- Forgetting to return a Promise inside a .then() callback
- Throwing inside an async function that is not awaited
- Using Promise.reject() without a handler
- Event emitters that reject internally without a listener
How to handle it
The fix is to attach a rejection handler. For async/await, wrap the call in a try/catch block. For .then() chains, add a .catch() at the end. If you truly want to ignore a rejection, attach a no-op catch, but that is rarely a good idea.
You can also add a global handler with process.on('unhandledRejection', (reason, promise) => { ... }) to log or clean up, but this is a safety net, not a replacement for proper error handling. In production, it is best to let the process crash and restart, because the app may be in an inconsistent state.
- Use try/catch around await expressions
- Add .catch() to every .then() chain
- Use process.on('unhandledRejection') for logging only
- Consider using a linter rule to catch missing handlers
- Set a custom handler if you need graceful shutdown
Common mistakes
- Thinking the warning is harmless and can be ignored; in modern Node.js it can terminate the process.
- Assuming that a .catch() on an inner Promise will also catch rejections from an outer Promise chain.
- Believing that adding a global unhandledRejection listener fixes the root cause; it only masks the error.
