Node.js crashes with an unhandled promise rejection
UnhandledPromiseRejectionWarning: This error originated either by throwing inside of an async function without a catch blockShort answer
A promise rejected and nothing handled it within a turn of the event loop. In current Node.js the default mode, throw, turns that into an uncaught exception, so the process exits. Find the rejected promise from the stack trace, then add await in a try/catch, a .catch(), or use Express 5, which forwards rejections.
Fix it fast
1Find out which cause you have
Log every rejection with its stack so you can see which call produced it. Register this early, in the entry file.
process.on('unhandledRejection', (reason, promise) => { console.error('Unhandled rejection at:', promise, 'reason:', reason) })2Match what you see, then jump to its fix
- 1
The stack ends inside an app.get or router.post callback declared async, on Express 4.An Express 4 async handler throws or rejectsFix - 2
The failing call is inside a handler or function that started .then() without return or await.A promise chain is started but not returned or awaitedFix - 3
The trace shows setTimeout, an EventEmitter listener or start-up code, not a route.A rejection happens outside a request, such as in a timer or event callbackFix
- 1
What does the error look like?
UnhandledPromiseRejectionWarning: This error originated either by throwing inside of an async function without a catch blockor by rejecting a promise which was not handled with .catch()
Cause 1 of 3
An Express 4 async handler throws or rejects
1Check
Express 4 does not look at what a handler returns. Express 5 does, and forwards a rejection to the error middleware.
npm ls express2Fix
Upgrade to Express 5, or in Express 4 wrap the body and pass the error to next.
// Express 4
app.get('/user/:id', async (req, res, next) => {
try {
res.send(await getUserById(req.params.id))
} catch (err) {
next(err)
}
})3Verify
Request the route with an id that fails. You get your error response and the process stays up.
curl -i http://localhost:3000/user/does-not-existConfirmed by expressjs.com
Cause 2 of 3
A promise chain is started but not returned or awaited
1Check
Express docs say that if a promise is not returned, Express does not know it exists, and its rejection would be unhandled.
grep -rn "\.then(" src/ | head2Fix
Return the chain, or await it, or end it with .catch(next).
app.get('/', (req, res, next) => {
doWork().then((v) => res.send(v)).catch(next)
})3Verify
Trigger the failing path and check the log for the handler output instead of a crash.
curl -i http://localhost:3000/Confirmed by expressjs.com
Cause 3 of 3
A rejection happens outside a request, such as in a timer or event callback
1Check
Nothing is waiting on those promises, so no framework can forward the error. Node.js raises it as an uncaught exception under the default throw mode.
grep -rn "setInterval\|setTimeout\|\.on(" src/2Fix
Catch inside the callback and log it. Keep the process.on('unhandledRejection') hook as a last-resort logger, not as the fix.
setInterval(async () => {
try {
await syncJobs()
} catch (err) {
console.error('sync failed', err)
}
}, 60_000)3Verify
Make syncJobs reject once and watch the log line appear while the process stays up.
node app.jsConfirmed by nodejs.org
How do I stop it coming back?
- Never leave a promise floating: await it, return it, or attach .catch().
- Do not set --unhandled-rejections=none or warn to hide the crash: those modes only silence or soften it, and the failed work stays unhandled.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Back end
Node.js crashes with throw er; // Unhandled 'error' event
Emitted 'error' event on Server instance at:
Node prints this when an event emitter, such as a server, stream or child process, emits 'error' and nothing listens for it.
4 causes, each with a fixBack end
Angular app shows 'Cannot GET /' when served by a Node.js server
Cannot GET /dashboard
Cannot GET / is Express saying no route or file matches the request.
3 causes, each with a fixBack end
Axios call from a React app comes back 404
404 (Not Found)
Status code 404 means a server answered, but it has nothing at that path.
3 causes, each with a fixBack end
bcrypt.hash throws 'data and salt arguments required'
Error: data and hash arguments required
The bcrypt package throws this when hash gets null or undefined for the password or for the salt.
4 causes, each with a fixBack end
bcryptjs rejects hash() or compare() with Illegal arguments
Error: Illegal arguments: string, undefined
bcryptjs checks the types of its two arguments and, when either is wrong, throws Illegal arguments followed by the typeof of the first and the second.
3 causes, each with a fixBack end
Express warns 'body-parser deprecated undefined extended'
body-parser deprecated undefined extended
The warning appears because urlencoded() was called without the extended option, which body-parser 1.x has warned about since version 1.4.0.
3 causes, each with a fix