Catching Unhandled Rejections

An unhandled rejection is a promise that rejects and never gets a rejection handler. It happens by accident: a function returns a promise, the caller forgets to return it or to await it, and the failure has nowhere to go.

In a browser the runtime reports it. The console shows an unhandled rejection error and the global error event fires, which is how error monitoring services pick it up. The page keeps running, so the failure is invisible unless someone is watching the console.

In Node the behaviour is stricter. Since version fifteen, an unhandled rejection terminates the process with a non-zero exit code, on the grounds that a silent failure in a server is worse than a crash. You can register a handler for the unhandledRejection event, and you can change the default behaviour entirely, but the better fix is always to find the call that is missing its handler.

How to prevent them in the first place. Return every promise from the function that starts it, so the caller can decide what to do with it. Await it inside a try block when you need to recover from the failure. Attach a catch handler to anything you fire and forget. And when you genuinely do not care about a failure, say so on purpose with a catch that logs, rather than by leaving the promise bare.

One trap to avoid. Adding a catch handler that only logs still leaves the outer promise fulfilled, so a caller who was relying on the rejection never learns about the failure. If the failure matters, throw again after logging.

Node emits an event when a rejection is not handled. Registering a listener both stops the process from crashing and gives you a place to report the failure.

// Node reports an unhandled rejection through a process event.
const seen = [];

process.on("unhandledRejection", (reason) => {
  seen.push(reason.message);
  console.log("caught unhandled:", reason.message);
});

// This promise rejects with nobody listening.
Promise.reject(new Error("nobody handled me"));

// Give the event loop a turn so the rejection is reported.
setTimeout(() => {
  console.log("reported:", seen.length);   // 1
}, 20);

The listener receives the rejection reason as its first argument, and a second argument holding the promise itself. That reason is not always an Error, so a production handler should check before it reads the message property, exactly as you would in a catch block.

There is a matching event for the case where a promise is rejected and then handled late, which the runtime calls a rejection being handled after the fact. The default is to warn about it, and you can listen for it too, but the practical advice is to fix the late handler rather than to silence the warning.

Two more pieces of production advice. Register the listener as early as possible, ideally in the first module that boots your application, so that failures during startup are caught too. And remember that a listener on this event is a safety net, not a fix. It stops the crash, but the underlying bug is still there and the operation that failed still did not happen.

Three habits cover almost every case: return the promise, await it inside a try block, or attach a catch handler explicitly.

// Always return or await the promise you start.
async function load() {
  return fetchProfile();
}

function fetchProfile() {
  return Promise.resolve({ name: "Ada" });
}

// A "fire and forget" call with an explicit handler.
fetchProfile().catch((err) => console.log("logged:", err.message));

// A helper that never lets a rejection escape.
const safely = (promise) => {
  if (promise && typeof promise.catch === "function") {
    return promise.catch((err) => {
      console.log("swallowed:", err.message);
      return null;
    });
  }
  return Promise.resolve(promise);
};

safely(Promise.reject(new Error("handled inside safely"))).then((value) => {
  console.log("value:", value);   // null
});

Returning the promise is the most important habit, because it hands the decision to the caller. If the caller does not want it, the caller's own lint rule will flag the unused promise, which turns a silent failure into a visible one.

The safely helper shows the fire-and-forget case handled properly. It attaches the handler and converts a rejection into a resolved value, so nothing escapes. The cost is that the failure is now invisible to the caller, so it should always log, and it should never be used where the caller genuinely needs to know about the failure.

Two more tools. The allSettled combinator handles a group of promises where you want every outcome rather than the first failure. And the finally method runs its callback whatever happened, which is where cleanup belongs so that the cleanup path cannot itself create an unhandled rejection.