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.
process.on('unhandledRejection', (reason, promise) => { console.error('unhandled:', reason); });
Try it
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.
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
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
throwmode, once you add an'unhandledRejection'listener, the process no longer crashes automatically. You are then responsible for deciding: log andprocess.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
awaitbefore an async call, firing offpromise.then(...)without a catch, and throwing inside an async event handler. Fix the cause rather than adding a global listener. - Every
asyncfunction returns a promise. An async callback passed tosetTimeout()or an emitter turns thrown errors into rejections. - Use
Promise.allSettled()when you start several promises and want all outcomes. WithPromise.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
awaitbefore they run. - Event names changed:
multipleResolveswas removed in Node.js 17; do not rely on it.