Dev.to WebDev 🛠 Dev 👁 0 📖 5 min read

Make Node exit on an unhandled rejection when Sentry is installed

I assumed that adding Sentry to a Node service wouldn't change how it crashes. An unhandled rejection kills a plain Node process, so it should kill mine too. It doesn't. I tested it, and the service kept answering reques

I assumed that adding Sentry to a Node service wouldn't change how it crashes. An unhandled rejection kills a plain Node process, so it should kill mine too. It doesn't. I tested it, and the service kept answering requests after the rejection. Sentry had the error, but the process never died, so nothing would have restarted it.

TL;DR

  • On Node 24 with no Sentry, an unhandled rejection kills the process with exit code 1. With @sentry/node 11.16.0 and a plain Sentry.init, the same rejection is reported at level error and the process keeps serving requests.
  • Sentry.onUnhandledRejectionIntegration({ mode: 'strict' }) brings the crash back. The event is still delivered, at level fatal, and the exit code is 1.
  • Any process.on('uncaughtException') or process.on('unhandledRejection') handler you add yourself keeps the process alive too, even with Sentry installed.

The lab

I wanted to know exactly what Sentry changes about crashes, so I ran eight setups and then the fix, each in its own process. Versions, from run-0-versions.txt:

v24.22.1
11.21.1
@sentry/node 11.16.0

Two pieces. A stub on :9999 plays Sentry ingest and logs every error event with its handled flag, mechanism and level. app.js is a tiny HTTP server on :9997 that fails once, 300 ms after boot, in one of two ways. A rejected promise that nobody awaits:

  if (MODE.startsWith('rejectstr')) Promise.reject('card_declined');
  else if (MODE.startsWith('reject')) Promise.reject(new Error('charge failed: card_declined'));
  else setTimeout(() => { throw new Error('queue worker blew up'); }, 0);

Or a plain throw inside a timer. After 3 seconds the runner checks whether the process is still alive and whether GET / still answers. The Sentry setup comes from the MODE variable, and the two "own handler" setups are one line each:

if (sentryModes[MODE]) Sentry.init({ ...base, ...sentryModes[MODE] });
if (MODE === 'throw-sentry-ownhandler') process.on('uncaughtException', e => console.log('own handler logged:', e.message));
if (MODE === 'reject-sentry-ownhandler') process.on('unhandledRejection', e => console.log('own handler logged:', e.message));

What each setup did

An unhandled rejection is a promise that rejected with no .catch and no await around it. An uncaught exception is a throw nobody catches. Node handles them with different defaults, and Sentry hooks them differently.

Setup Failure Process after 3s Exit code Events at ingest
no Sentry rejection dead 1 0
Sentry.init defaults rejection alive, serving none 1, level error
onUnhandledRejectionIntegration({ mode: 'strict' }) rejection dead 1 1, level fatal
no Sentry throw in timer dead 1 0
Sentry.init defaults throw in timer dead 1 1, level fatal
defaults plus my own uncaughtException handler throw in timer alive, serving none 1, level fatal
defaults plus my own unhandledRejection handler rejection alive, serving none 1, level error
Sentry.init defaults rejection with a string alive, serving none 1, level error

The second row surprised me. Here is run-2.txt:

## MODE=reject-sentry
process alive after 3s: yes, still serving requests: yes, exit code: still running
events at ingest: 1
{"message":"charge failed: card_declined","handled":false,"mechanism":"auto.node.onunhandledrejection","level":"error"}

Why a plain init stops the crash

Sentry's rejection integration registers its own unhandledRejection listener. Once any listener exists, Node no longer applies its default behavior, which is to throw and exit. The integration has a mode option, and the default is warn. In warn mode it captures the error, prints a warning to the console, and returns. That is all of it. I confirmed this in the installed package, source-facts.txt has the grep lines: mode: options.mode ?? "warn" in onunhandledrejection.js.

Two side effects follow from that one default.

  • The process stays up in whatever state the failed code left it. A worker that was halfway through a job is still running its loop. A container with restart: unless-stopped never restarts, because the process never exits. I didn't run Docker for this, but it follows directly from exit code none in the table.
  • The severity is lower. In warn mode the event is error. In strict mode it is fatal. If you page on level:fatal, a rejection under the default setup won't trip that alert. A throw in a timer is fatal either way, as the table shows.

The uncaught exception side is different

For a throw nobody catches, plain Sentry.init still exits. run-5.txt shows exit code 1 and one fatal event delivered before the process went away. The source has a 2 second timeout (const timeout = 2e3 in onuncaughtexception.js) to flush the event before exiting, and that delivery worked in my run.

The catch is the option exitEvenIfOtherHandlersAreRegistered. It defaults to false. So if you, a library or your framework already registered an uncaughtException handler, Sentry reports the error and leaves the exit decision to that other handler. In run 6 the handler only logged, and the process lived on. A handler like process.on('uncaughtException', err => logger.error(err)) does exactly that.

Make it crash again and keep the report

This is instrument.js, loaded before anything else:

const Sentry = require('@sentry/node');
Sentry.init({
  dsn: process.env.SENTRY_DSN,
  integrations: [Sentry.onUnhandledRejectionIntegration({ mode: 'strict' })],
});

And run-9.txt, the same rejection against it:

## MODE=reject-recipe
process alive after 3s: no, still serving requests: no, exit code: 1
events at ingest: 1
{"message":"charge failed: card_declined","handled":false,"mechanism":"auto.node.onunhandledrejection","level":"fatal"}

Exit code 1, one event, level fatal. Your orchestrator (Docker, systemd, whatever you run) sees a crash and restarts the service. The error is in the tracker with the stack that caused it.

A string is not an Error

Run 8 rejected with a plain string, Promise.reject('card_declined'). The event arrived with the message card_declined, but a string has no stack, so there is nothing to group by except that text. If you reject with strings anywhere, fix it at the source. Sentry only reports what it is given.

Checklist before you trust your crash handling

  1. Throw a rejection on purpose in staging and watch the process. Does it exit, or does it keep serving?
  2. Search the codebase and your dependencies for process.on('uncaughtException' and process.on('unhandledRejection'. Each one overrides the default exit.
  3. Decide if you want strict. If a half-failed worker is worse than a restart for you, you do.
  4. Check which severity your alert rules match. fatal and error are different rules.
  5. Check the shutdown path: is the event actually delivered before exit? Mine was, with a local stub, so test it against your own network.
  6. Reject with Error objects, not strings or plain objects.

What I did not test

One SDK version (@sentry/node 11.16.0), one Node version (24.22.1), a plain HTTP server on localhost, and a stub instead of a real ingest. I did not test Express, Fastify, Next.js or Docker restart policies. Frameworks and libraries can install their own handlers, which is exactly the case where this matters. The behavior is in the SDK, so it should not depend on which server receives the events, but I only ran it against the stub.

If you run Node services behind a restart policy, do you let an unhandled rejection crash the process, or do you let it limp along and alert on it?

📰 Read the original article on Dev.to WebDev

Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.