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/node11.16.0 and a plainSentry.init, the same rejection is reported at levelerrorand the process keeps serving requests. -
Sentry.onUnhandledRejectionIntegration({ mode: 'strict' })brings the crash back. The event is still delivered, at levelfatal, and the exit code is 1. - Any
process.on('uncaughtException')orprocess.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-stoppednever 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
warnmode the event iserror. Instrictmode it isfatal. If you page onlevel:fatal, a rejection under the default setup won't trip that alert. A throw in a timer isfataleither 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
- Throw a rejection on purpose in staging and watch the process. Does it exit, or does it keep serving?
- Search the codebase and your dependencies for
process.on('uncaughtException'andprocess.on('unhandledRejection'. Each one overrides the default exit. - Decide if you want
strict. If a half-failed worker is worse than a restart for you, you do. - Check which severity your alert rules match.
fatalanderrorare different rules. - Check the shutdown path: is the event actually delivered before exit? Mine was, with a local stub, so test it against your own network.
- Reject with
Errorobjects, 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?
Top comments (0)