Node.js app crashing on an unhandled promise rejection
Short answer: Since Node.js 15, a promise that rejects with nobody handling it crashes the process by default. That's deliberate: an unhandled error means your app may be in a state nobody planned for. The fix is to find the promise that's missing an await, a try/catch or a .catch(), usually in a route handler, a background task started without awaiting it, or a callback that calls an async function. Add a process.on('unhandledRejection') handler only to log the details and shut down cleanly, not to keep running as if nothing happened.
What the crash means
A promise represents work that finishes later, such as a database query or an API call. If it fails, it rejects. If your code has attached no handler for that rejection, Node.js has to decide what to do.
The Node.js command-line documentation lists the modes for --unhandled-rejections. The default since version 15 is throw: Node emits the unhandledRejection event, and if no handler is set, raises the rejection as an uncaught exception, which ends the process. Before version 15 the default was only a warning, which is why older apps that "worked fine" start crashing after a Node upgrade.
Your process manager, container platform or hosting service then restarts the app. Customers see failed requests or a brief outage, and the logs fill with the same error.
Finding the culprit
The error output includes the rejection reason and, if it's an Error object, a stack trace. Start there:
- Read the stack trace from the top. The first lines in your own code, not in
node_modules, point to where the failing call was made. - If there's no useful stack, the code probably rejected with a string or plain object. Search for
reject(andthrowstatements that don't usenew Error(...). - Check what changed recently. A new integration, a new background job or an upgraded library are the usual suspects.
- Reproduce it. Many rejections only happen when an outside service is slow or down. Point the app at a failing test endpoint to trigger it.
The common patterns behind it
An async function called without await
app.post('/booking', (req, res) => {
sendConfirmationEmail(req.body.email); // returns a promise, never awaited
res.json({ ok: true });
});
If the email service fails, nobody handles the rejection. Either await it inside a try/catch, or, if it's meant to run in the background, attach a .catch() that logs the failure.
Async route handlers in older frameworks
Some web frameworks don't forward errors from async handlers to their error middleware. A rejected promise inside the handler escapes. Wrap handlers so errors go to next(err), or use a framework version that handles async errors natively. Express 5, for example, passes rejected promises from route handlers to the error handler.
Callbacks that call async code
Event emitters, timers and array methods like forEach don't wait for promises. items.forEach(async item => await save(item)) starts every save and handles none of the failures. Use a for...of loop with await, or Promise.all or Promise.allSettled with a single place to handle errors.
Promise.all without a catch
When one promise in Promise.all rejects, the combined promise rejects. If nothing awaits it or catches it, that's another unhandled rejection.
What a global handler is for
The Node.js process documentation describes the unhandledRejection event, and gives a strong warning about the related uncaughtException event: it's "a crude mechanism for exception handling intended to be used only as a last resort", and unhandled exceptions mean the application is in an undefined state.
A sensible global handler:
- logs the reason and stack trace to your error monitoring
- stops accepting new requests
- lets in-flight requests finish where possible
- exits with a non-zero code so the process manager restarts a clean copy
What it shouldn't do is swallow the error and carry on. That hides bugs and can leave connections, locks or half-written data behind.
Don't silence it with a flag
The --unhandled-rejections flag also accepts warn and none. Switching to those makes the crashes stop, but the errors still happen; they just stop being visible. Use them only as a short-term measure while you deploy a fix, if at all.
Preventing it next time
- Turn on lint rules that flag promises that aren't awaited or handled. Most linters for JavaScript and TypeScript have one.
- Always reject with Error objects, so you get a stack trace.
- Give background work its own error handling and a log line that names the job.
- Monitor restarts. A process that restarts several times an hour has a problem even if users rarely notice.
- Test failure paths: a timeout from a payment API, a database that's briefly unavailable, an email provider returning an error.
A worked example
An illustrative Denver appointment booking API started restarting several times a day after an upgrade from Node 14 to 20. The logs showed an unhandled rejection from the SMS reminder service with a timeout error. The route that created a booking called sendReminderSms() without awaiting it. Under Node 14 the failure had only produced a warning nobody read. The team added a .catch() that logged the failure and queued a retry, added a global handler that logged and exited cleanly, and turned on a lint rule for unhandled promises. The restarts stopped, and failed reminders now show up in the logs.
FAQ
Why didn't this happen before the Node upgrade?
Node 15 changed the default from a warning to throw. The bug was there; it just didn't stop the process.
Is it safe to keep the process running after logging?
Generally no. Log, finish in-flight work if you can, and exit so a clean process takes over.
Does TypeScript prevent this?
Not by itself. Type checks don't require promises to be handled, but lint rules can.
What about the browser?
Browsers fire an unhandledrejection event too, but they don't close the page. It's worth sending those to your error monitoring as well.
If your Node.js app keeps restarting and you can't find why, send us the error output and we'll help you trace the rejection.