Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Events and Timers

captureRejections in Node.js EventEmitter

Reference for the captureRejections option of Node.js EventEmitter: how rejected async listeners become 'error' events, the rejection symbol and its pitfalls.

An EventEmitter calls its listeners synchronously and ignores what they return. That is a problem for async listeners: if one throws after an await, the promise it returned rejects, nobody is watching that promise, and the process ends with an unhandled rejection. captureRejections is an opt-in feature that attaches a handler to every promise a listener returns and routes the failure back into the emitter.

With the option on, a rejected listener promise is turned into an 'error' event on the same emitter (or into a call to a custom handler method). Ordinary error handling then works the way it does for synchronous listeners.

NODE
const emitter = new EventEmitter({ captureRejections: true });
emitter.on('error', (err) => console.log('caught:', err.message));

Try it

Node.js Async listener failure becomes an error event

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 A custom rejection handler

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
new EventEmitter({ captureRejections: true })
EventEmitter.captureRejections = true          // default for emitters created later
emitter[Symbol.for('nodejs.rejection')] = (err, eventName, ...args) => { }
Name Description
captureRejections (option) Boolean. When true, promises returned by listeners of this emitter are observed. Default false.
EventEmitter.captureRejections Static property that sets the default for every emitter created afterwards. It does not change existing emitters.
captureRejectionSymbol Exported by node:events; equal to Symbol.for('nodejs.rejection'). A method under this key replaces the default routing.

What happens on rejection:

  1. If the emitter has a function under the rejection symbol, it is called with the error, the event name and the original emit arguments.
  2. Otherwise the emitter emits 'error' with the error as the only argument. If nothing listens for 'error', the normal rule applies and the error is thrown, which usually means an uncaught exception.

Usage notes

  • Only listeners that return a thenable are observed. Synchronous throws are not affected by this option; they still propagate out of emit().
  • The option is per emitter. Subclasses must pass it to super(), as the second example does.
  • If a custom rejection handler itself throws, the error is emitted as an 'error' event. Keep that handler simple and synchronous.
  • The 'error' event is emitted asynchronously, after the promise rejected, so code that wraps emit() in try/catch will never see it.
  • Do not rely on the feature for flow control. A rejected listener does not stop the other listeners of the same event; they were already called.
  • Enabling it globally with EventEmitter.captureRejections = true is convenient in applications, but libraries should set the option on their own emitters instead of changing a global.
  • Without the option, a rejected listener leads to the unhandledRejection path, which in current Node.js versions terminates the process unless a handler exists.