Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Node.js crashes with an unhandled promise rejection

ErrorUnhandledPromiseRejectionWarning: This error originated either by throwing inside of an async function without a catch block

Short 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.

  • Applies to Node.js 22, Express 5, Express 4
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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)
    })
  2. 2Match what you see, then jump to its fix

    1. 1The stack ends inside an app.get or router.post callback declared async, on Express 4.An Express 4 async handler throws or rejectsFix
    2. 2The 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. 3The 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

What does the error look like?

  • UnhandledPromiseRejectionWarning: This error originated either by throwing inside of an async function without a catch block
  • or 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 express

2Fix

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-exist

Confirmed by expressjs.com

Did this fix it?

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/ | head

2Fix

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

Did this fix it?

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.js

Confirmed by nodejs.org

Did this fix it?

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.