A Node.js 24 worker service crashed overnight on a rejected fire-and-forget call: what path took it down, and how do the --unhandled-rejections modes change it?
answer
- default mode name since Node 15
- listener first, then uncaught exception
- origin set to 'unhandledRejection'
- a log-only listener disarms the crash
- strict, warn, warn-with-error-code, none
basics
~20 sUnder Node 24's default mode, throw, Node emits 'unhandledRejection'; with no listener it raises the rejection as an uncaught exception, which crashes the process with exit code 1. The strict, warn, warn-with-error-code and none modes change that path.
solid answer
~40 sWhen a promise rejects and no handler is attached within a turn of the event loop, Node applies the `--unhandled-rejections` mode. The default since Node 15, `throw`, first emits `process.on('unhandledRejection')`; if nothing listens, it raises the reason as an uncaught exception, so `uncaughtExceptionMonitor` and `'uncaughtException'` see it with origin `'unhandledRejection'`, and with no handler the process exits with code 1. A non-Error reason is wrapped in an error whose code is `ERR_UNHANDLED_REJECTION`. `strict` raises the uncaught exception even when an `unhandledRejection` listener exists; `warn` always prints a warning and never crashes; `warn-with-error-code` warns and sets `process.exitCode` to 1 but keeps running; `none` prints nothing. The trap: in `throw` mode any `unhandledRejection` listener counts as handling, so a log-only listener switches the crash off.
code
javascript · 7 lines// crash.cjs
async function sendAuditEvent() {
throw new Error('audit endpoint unreachable');
}
sendAuditEvent(); // fire-and-forget: no await, no .catch()
setTimeout(() => console.log('still alive'), 100);go deeper
Know that a Node 24 process crashes with exit code 1 on an unhandled rejection by default, and that the setting is called --unhandled-rejections with throw as its default.
Walk the default path in order: unhandledRejection, then uncaughtExceptionMonitor and uncaughtException with origin 'unhandledRejection', then exit 1. Then contrast it with each of the other four modes.
Reconstruct a real crash from its symptoms, spot the log-only listener that silently disarms the default, and choose a mode and listener policy a fleet can rely on.
Treat the mode as a fleet default: set it once through NODE_OPTIONS, decide whether strict is worth its stricter failures, and make survival a deliberate exception rather than a library side effect.
## When Node decides a rejection is unhandled A rejected promise is **unhandled** in Node.js when no rejection handler has been attached to it within a turn of the event loop. Node then hands it to the policy chosen with the `--unhandled-rejections=mode` flag. The language-level rules (what makes a promise "floating", how a late `.catch()` is timed) belong to the JavaScript lesson on unhandled rejections; this answer is about what the Node process does next. If a handler is attached later, Node emits `'rejectionHandled'` for that promise, which matters only when the process survives the first event, for example through a listener or a warn mode. ## The default path in Node 24 The default mode is `throw`, and it has been since Node 15. Before that, an unhandled rejection only printed a warning. In Node 24 the path is: 1. Node emits `process.on('unhandledRejection', (reason, promise) => ...)`. 2. If at least one listener exists, the rejection counts as handled and the process keeps running. 3. If none exists, Node prepares an error: an `Error`-like reason is used as is, and anything else (a string, `undefined`) is wrapped in an `UnhandledPromiseRejection` error whose `code` is `ERR_UNHANDLED_REJECTION`. 4. Node raises that error as an **uncaught exception**: `uncaughtExceptionMonitor` and then `'uncaughtException'` are emitted with `origin` set to `'unhandledRejection'`. 5. With no `'uncaughtException'` listener, Node prints the stack trace to `stderr`, emits `'exit'` with code 1 and exits with **code 1**. One case ignores the flag: a rejection during the command-line entry point's ES module static loading phase is always raised as an uncaught exception. ## The five modes | Mode | `unhandledRejection` emitted | Process crashes when nothing handles it | Effect on exit code | |---|---|---|---| | `throw` (default) | Yes, first | Yes, as an uncaught exception | 1 on the crash | | `strict` | Yes, but only after the uncaught exception was handled | Yes, even if an `unhandledRejection` listener exists | 1 on the crash | | `warn` | Yes | No; a warning is always printed | Unchanged | | `warn-with-error-code` | Yes | No; a warning is printed when no listener exists | `process.exitCode` set to 1 | | `none` | Yes | No; no warning at all | Unchanged | The differences that interviewers probe: - **`strict` versus `throw`.** `strict` raises the uncaught exception first and consults `unhandledRejection` only if an `'uncaughtException'` listener handled it. A logging `unhandledRejection` listener therefore cannot disarm `strict`. - **`warn-with-error-code`** keeps the process alive and only changes the code it exits with later, which suits a batch script or test run that should finish but must report failure. - **`none`** makes an unhandled rejection with no listener invisible: no warning, no crash, no exit code. ## The overnight crash, reconstructed The worker loop called `sendAuditEvent(job)` without `await` and without `.catch()`, so the job could continue while the event was sent. During a network blip the call rejected. No code had attached a handler, the service ran with default flags and no `unhandledRejection` listener, so the rejection became an uncaught exception: stack trace on stderr, exit code 1, every in-flight job abandoned, and the supervisor restarted the process. Nothing about Node misbehaved; the default exists precisely so that a forgotten rejection stops the process instead of leaving work silently undone. ## Choosing a process-level policy - **Keep the crash.** Leave the default `throw`, or choose `strict`, and fix the call site with a handler; restarting a clean process is cheaper than running one in an unknown state. - **Do not add a log-only listener.** In `throw` mode it makes every unhandled rejection survivable, which is a policy change disguised as logging. - **If you add a listener, finish the job in it.** Log the reason, set `process.exitCode = 1`, and exit or rethrow, so the listener records the failure without hiding it. - **Set the mode where every process sees it.** `--unhandled-rejections` is allowed in `NODE_OPTIONS`, so one environment variable applies the policy to every Node process a service starts. - **Use `warn` and `none` only knowingly.** Both turn a programming error into log noise, or into nothing at all.
- Why does adding a log-only process.on('unhandledRejection') listener stop the crash?In the default `throw` mode Node raises the rejection as an uncaught exception only when `unhandledRejection` was not handled, and any listener counts as handling. So a listener that merely logs changes the policy from crash to survive. Either make the listener exit or rethrow, or run with `--unhandled-rejections=strict`, which raises the exception regardless.
- What does a crashed process print when the rejection reason is not an Error?Node wraps the value in an `UnhandledPromiseRejection` error with code `ERR_UNHANDLED_REJECTION` and a message saying the promise rejected with that reason. Because the wrapper is created by Node, its stack trace does not point at the code that rejected, which is one more reason to reject with real `Error` objects.
- Node 24 only prints a warning for an unhandled rejection by default.
- A log-only unhandledRejection listener keeps the crash and just adds logging.
- warn-with-error-code exits immediately with code 1.
- strict and throw are two names for the same behaviour.
- The none mode still crashes, just without printing anything.
Assumes Node.js 24; the default --unhandled-rejections mode became throw in Node 15, before which an unhandled rejection only printed a warning.