Node.js Reference ยท process
Node.js uncaughtException event
Reference for the process uncaughtException event in Node.js: when it fires, the origin argument, why you should log and exit, and uncaughtExceptionMonitor.
When an error is thrown and nothing catches it, Node.js prints the stack trace and ends the process with code 1. The 'uncaughtException' event on process lets you run code first: you can log the error, flush data and shut down on your own terms.
It is a safety net, not an error-handling strategy. After an uncaught exception the program is in an unknown state, so the safe pattern is to record the problem and exit.
process.on('uncaughtException', (err, origin) => { console.error('fatal:', err.message, origin); process.exit(1); });
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('uncaughtException', (err, origin) => { }) process.on('uncaughtExceptionMonitor', (err, origin) => { }) process.setUncaughtExceptionCaptureCallback(fn | null) process.hasUncaughtExceptionCaptureCallback()
| Name | Description |
|---|---|
err |
The thrown value (usually an Error, but anything can be thrown). |
origin |
'uncaughtException' for a normal throw, or 'unhandledRejection' when a rejected promise became an exception. |
Returns: the listener's return value is ignored.
Errors / edge cases: if the handler itself throws, the process exits with code 7. With --unhandled-rejections=strict rejections are raised as uncaught exceptions even when a rejection listener exists.
Usage notes
- Log, clean up synchronously, then exit. Calling
process.exit(1)in the handler is the recommended pattern. Continuing as if nothing happened can leave half-updated state, open transactions and leaked handles. - Do not use it for flow control. Wrap risky code in
try/catch, handle promise rejections and giveEventEmitters an'error'listener. A global handler cannot tell you which request failed. uncaughtExceptionMonitorruns before the normal handler and cannot stop the crash. It is meant for crash reporters that must always see the error. With--abort-on-uncaught-exception, the monitor still runs before the abort.- A handler suppresses the default crash, including the stack trace print and the exit code
1. If you swallow the error, nobody learns about it. - A thrown error inside a Promise does not reach this event as a plain throw; it is a rejection (see
unhandledRejection). - Domains and capture callback:
setUncaughtExceptionCaptureCallback()is a lower-level hook that replaces all'uncaughtException'listeners; only one can be set. Use it only if you build tooling. - Automatic reports: start Node with
--report-uncaught-exceptionto also write a diagnostic report. - Worker threads: an uncaught error in a worker is delivered to the parent as the worker's
'error'event.