Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท process

Node.js unhandledRejection event

Reference for the process unhandledRejection and rejectionHandled events in Node.js: when they fire, the --unhandled-rejections modes, and safe patterns.

A promise that is rejected but has no .catch() or try/await around it is an unhandled rejection. Since Node.js 15 the default is to treat it like an uncaught exception: the process prints the error and exits with code 1.

The 'unhandledRejection' event on process fires first, giving you a chance to log the problem. Its partner 'rejectionHandled' reports the case where a handler is attached late.

NODE
process.on('unhandledRejection', (reason, promise) => {
  console.error('unhandled:', reason);
});

Try it

Node.js Logging an unhandled rejection

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Handling a rejection too late

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
process.on('unhandledRejection', (reason, promise) => { })
process.on('rejectionHandled', (promise) => { })
Name Description
reason The value the promise was rejected with. It is often an Error, but can be anything.
promise The rejected Promise itself.

Returns: listener return values are ignored.

Modes (--unhandled-rejections=...):

Mode Behaviour
throw (default) Emit 'unhandledRejection'. If there is no listener, raise an uncaught exception.
strict Raise an uncaught exception at once; if it is handled, then emit 'unhandledRejection'.
warn Always print a warning, and emit 'unhandledRejection'.
none Silence warnings, still emit 'unhandledRejection'.
warn-with-error-code Warn, emit the event, and set exit code 1 if no listener handled it.

Errors / edge cases: a listener that itself throws triggers 'uncaughtException'.

Usage notes

  • Registering a listener changes the default. Under throw mode, once you add an 'unhandledRejection' listener, the process no longer crashes automatically. You are then responsible for deciding: log and process.exit(1) is usually right.
  • Detection happens after the microtask queue drains. A rejection that gets a .catch() in the same turn never fires either event; one handled later fires 'unhandledRejection' first and 'rejectionHandled' when the handler is attached.
  • The usual causes: forgetting await before an async call, firing off promise.then(...) without a catch, and throwing inside an async event handler. Fix the cause rather than adding a global listener.
  • Every async function returns a promise. An async callback passed to setTimeout() or an emitter turns thrown errors into rejections.
  • Use Promise.allSettled() when you start several promises and want all outcomes. With Promise.all() the first rejection is handled, but later ones are silently ignored once the first handler is attached.
  • ESLint can help: a "no floating promises" rule catches missing await before they run.
  • Event names changed: multipleResolves was removed in Node.js 17; do not rely on it.