EC
ERR_UNHANDLED_ERROR
Node.jsERRORCriticalGeneralHIGH confidence

An unhandled error occurred.

Production Risk

Critical. An unhandled error will crash the Node.js process, leading to service downtime. It is a sign of an incomplete or non-robust error handling strategy.

What this means

This is a generic wrapper for an error that was thrown but not caught, particularly within event emitters. For example, if an 'error' event is emitted on an EventEmitter instance but there is no listener for it, Node.js will wrap the original error in `ERR_UNHANDLED_ERROR` and crash the process. This behavior is designed to prevent applications from continuing in an unknown and potentially unstable state.

Why it happens
  1. 1An 'error' event was emitted on an EventEmitter without a corresponding listener.
  2. 2An error occurred in an asynchronous operation, like a stream or promise, without a `.catch()` or `try...catch` block to handle it.
How to reproduce

This error occurs when an EventEmitter instance (such as a stream, HTTP server, or child process) emits an 'error' event, and no `.on('error', ...)` listener has been attached to that instance.

trigger — this will error
trigger — this will error
const { EventEmitter } = require('events');
const myEmitter = new EventEmitter();
// No 'error' listener is attached, so this will crash the process.
myEmitter.emit('error', new Error('whoops!'));

expected output

Error: whoops!
...stack trace...
[...and the process terminates]

Fix 1

Add an Error Event Listener

WHEN Working with any EventEmitter-based object.

Add an Error Event Listener
const { EventEmitter } = require('events');
const myEmitter = new EventEmitter();
myEmitter.on('error', (err) => {
  console.error('An error occurred:', err);
});
myEmitter.emit('error', new Error('whoops!'));

Why this works

Always attach an error event listener to EventEmitters to handle potential errors gracefully. This prevents the application from crashing and allows for proper logging and recovery.

Fix 2

Use Process-wide Uncaught Exception Handler

WHEN As a last resort or for monitoring purposes.

Use Process-wide Uncaught Exception Handler
process.on('uncaughtException', (err, origin) => {
  console.error('Caught exception:', err, 'Exception origin:', origin);
  // It's recommended to gracefully shut down the process here.
  process.exit(1);
});

Why this works

While it can prevent a crash, `uncaughtException` is a crude mechanism. The recommended practice is to handle errors at their source. Using this listener means the application is in an unknown state.

Code examples
Triggerjs
const { EventEmitter } = require('events');
const myEmitter = new EventEmitter();
// No 'error' listener is attached, so this will crash the process.
myEmitter.emit('error', new Error('whoops!'));  // this triggers ERR_UNHANDLED_ERROR
Handle in try/catchjs
try {
  // operation that may throw ERR_UNHANDLED_ERROR
  riskyOperation()
} catch (err) {
  if (err.code === 'ERR_UNHANDLED_ERROR') {
    console.error('ERR_UNHANDLED_ERROR:', err.message)
  } else {
    throw err
  }
}
Defensive pattern to avoid itjs
const { EventEmitter } = require('events')
const emitter = new EventEmitter()
emitter.on('error', (err) => {
  console.error('Handled:', err.message)
})
// Now emitting error won't crash the process
What not to do

✕

✕

Sources
Official documentation ↗

https://github.com/nodejs/node/blob/main/lib/events.js

More information ↗

Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev

← All Node.js errors