Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Concepts and Pitfalls

Unhandled errors in Node.js

What happens when a Node.js error is not handled: uncaught exceptions, unhandled promise rejections, exit codes, and the right use of the process handlers.

An error is unhandled when nothing catches it. In Node.js that happens in two ways. A synchronous throw (or an 'error' event with no listener) that reaches the top of the call stack is an uncaught exception. A promise that rejects with no .catch() or await attached by the end of the current turn is an unhandled rejection.

Since Node 15 both end the process by default: an uncaught exception prints the stack and exits with code 1, and an unhandled rejection is converted into an uncaught exception, also exiting with 1. That is deliberate. After an unexpected error, the program's state may be inconsistent, and continuing silently is more dangerous than restarting.

NODE
process.on('unhandledRejection', (reason) => { /* log, then exit */ });
process.on('uncaughtException', (err, origin) => { /* log, then exit */ });

Try it

Node.js Default behavior in child processes

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 Handlers: log and exit deliberately

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.

How each case behaves

Situation Default result With a handler
Uncaught exception Stack trace, exit code 1. uncaughtException listeners run; the process keeps running unless you exit.
Unhandled rejection Becomes an uncaught exception, exit code 1. unhandledRejection listeners run; if one exists, the default crash does not happen.
'error' event without listener Thrown, so an uncaught exception. Add an 'error' listener on the emitter.
Rejection handled later A late .catch() after the turn ends still triggers unhandledRejection, then rejectionHandled. Attach handlers immediately.

The origin argument of uncaughtException is 'uncaughtException' for a thrown error or 'unhandledRejection' when a rejection was turned into an exception. The --unhandled-rejections= flag can change the default (throw, strict, warn, none, warn-with-error-code), but changing it hides bugs in production.

Usage notes

  • Handlers are for logging and cleanup, not recovery. After uncaughtException the process is in an unknown state. Log, flush what you must, and exit with a non-zero code; let a supervisor restart it.
  • Do not swallow errors. A handler that only logs and carries on turns a crash into a zombie that fails in strange ways later.
  • Set process.exitCode rather than calling process.exit() when you can, so pending output is flushed. See process.exitCode.
  • Attach rejection handlers in the same turn. await, .catch() or Promise.allSettled() should be in place before control returns to the event loop.
  • Fire-and-forget async calls (doWork(); without await) are the usual source. Add .catch() or mark them with void only after you handle errors inside.
  • EventEmitter with captureRejections: true routes rejections of async listeners to the 'error' event; see captureRejections.
  • process.on('exit') listeners run synchronously; no async work completes there.
  • Test it in a child process, as the examples do, because the real crash would end your test runner.