Unhandled Rejections: The Silent Production Killer A Promise makes failure routable. It does not make it mandatory. A rejection nobody observes is not an error you see; it is an event you may or may not be listening for.
The bug report was one line: "It said Save failed, so I clicked Save again, and now everything is duplicated."
The screen was an admin tool for editing a customer account. One Save button, four writes: profile, preferences, billing contact, and an audit-log entry. The code fired all four in parallel with Promise.all. The audit-log endpoint had a bad deploy and returned a 500. Promise.all rejected on the spot, the UI showed a red "Save failed" banner, and the user did what any reasonable person would do. They pressed Save again.
The other three writes had already succeeded. The retry wrote them a second time: new version numbers, a second round of notification emails, and a duplicate billing contact.
The same week, our error tracker held a steady stream of Unhandled promise rejection events that nobody had triaged, because none of them had a stack trace pointing at anything useful.
In the last post I covered how callbacks hand away control over where errors go. Promises give some of that control back, but only conditionally. A promise can reject, and nothing in the language forces anyone to be listening. By the end of this post you will know what the runtime actually does with a rejection nobody handled, the three ways production code creates them, and the three habits that stop it.
The mechanism: every link in a chain is a new place to lose an error
A Promise is a small state machine with three states: pending, fulfilled, and rejected. It starts pending, settles exactly once, and never changes after that. Every .then(), .catch(), and .finally() returns a new promise, and a rejection travels down the chain, skipping .then() handlers, until something handles it.
That last sentence is the whole problem. Each link in a chain is a new promise, and each new promise is a new place for a rejection to end up with nobody attached.
showError handles request. It does not handle derived #1. If request rejects, the rejection flows into derived #1, which has no handler, and the runtime reports it, even though a .catch() exists on the other branch.
When a rejected promise still has no handler after the current microtask queue drains, the runtime reports it. What happens next depends on where your code runs:
Older versions of Node only printed a warning and carried on. That default changed in Node 15, and plenty of teams still have muscle memory from before.
So "silent killer" means two different things. On the server it is literal: one forgotten .catch() can end the process. In the browser it is quieter and often worse. The page keeps running with a chain that never finished: a loading flag that never flips back, a spinner that never stops, a form stuck half-submitted. Nothing crashes. Nothing recovers either.
The real-world cost: three ways production code loses a rejection
Promise.all is all-or-nothing for results, not for effects
This is the bug from the opening
async function saveAll(draft: Draft) {
try {
await Promise.all([
api.updateProfile(draft.profile),
api.updatePreferences(draft.prefs),
api.updateBilling(draft.billing),
api.writeAuditLog(draft),
]);
toast.success('Saved');
} catch (err) {
toast.error('Save failed'); // which of the four? we no longer know
}
}
Promise.all rejects the moment the first input rejects. Two details are easy to miss:
- It does not cancel the other promises. The remaining requests keep running, and their side effects still happen. Only their results are discarded. The client believes the operation failed; the server applied most of it.
-
It reports only the first rejection. If two inputs fail, the second reason is swallowed.
Promise.allattaches its own handlers to every input, so the second failure doesn't even surface as an unhandled rejection. You lose information about the failure exactly when you need it.
The floating promise
A floating promise is any promise that nobody returned, awaited, or handled. Its rejection has no owner.
function onSave() {
saveDraft(draft); // returns a promise that nothing holds
}
items.forEach(async (item) => {
await api.sync(item); // forEach ignores the returned promise
});
afterSync(); // runs immediately, before any sync has finished
The second example does two kinds of damage. A rejection from api.sync becomes an unhandled rejection, and afterSync() runs before any of the work it was supposed to follow. The same shape appears in new Promise(async (resolve) => ...), where a throw inside the async executor never reaches the promise you are constructing.
The handler that never sees the error
Two ways to write a handler that looks correct and never runs.
async function loadUser(id: string) {
try {
return fetchUser(id); // returns the promise; the try block is already over
} catch (err) {
return fallbackUser(); // never runs for a rejection
}
}
Without await, the function returns the promise and exits the try block before it settles. The rejection happens later, in the caller's context, where your catch can't see it. The second is the split chain from the mechanism section:
const request = fetchDashboard();
request.then(renderDashboard); // derived promise with no handler
request.catch(showError); // handles `request`, not the line above
If request rejects, showError runs, and the line above it also produces an unhandled rejection. If renderDashboard throws, showError never sees it at all.
The fix: three habits
1. Pick the combinator that matches the failure you can tolerate
Promise.all is not wrong. It is the right tool when the operations depend on each other and a partial result is useless. The mistake is using it by default for independent work.
For the save screen, the operations are independent, so each outcome should be visible:
const jobs = [
{ name: 'profile', run: () => api.updateProfile(draft.profile) },
{ name: 'preferences', run: () => api.updatePreferences(draft.prefs) },
{ name: 'billing', run: () => api.updateBilling(draft.billing) },
{ name: 'audit log', run: () => api.writeAuditLog(draft) },
];
const results = await Promise.allSettled(jobs.map((job) => job.run()));
const failed = results.flatMap((result, i) =>
result.status === 'rejected' ? [{ name: jobs[i].name, reason: result.reason }] : []
);
if (failed.length === 0) return toast.success('Saved');
failed.forEach(({ name, reason }) => reportError(reason, { job: name }));
toast.warning(`Saved, except: ${failed.map((f) => f.name).join(', ')}`);
return failed.map((f) => f.name); // the retry button re-runs only these
Now the user sees what actually happened, the error tracker gets one event per failure with the job name attached, and retry re-runs only what failed.
Two honest limits. allSettled does not cancel anything either, and an AbortController can stop requests in flight but cannot undo a write the server already applied. If the four writes must be atomic, the answer is a single server-side batch endpoint with a transaction. Until then, make retries safe with idempotency keys so that re-running a write that already landed is harmless.
2. Give every promise an owner
The rule is short: every promise is returned, awaited or handled. Where a call is genuinely fire-and-forget, make that explicit and give it a handler:
function track(promise: Promise<unknown>, context: string): void {
promise.catch((err) => reportError(err, { context }));
}
function onSave() {
track(saveDraft(draft), 'save-draft');
}
Then make the compiler enforce it. These rules need type-aware linting with typescript-eslint:
{
"rules": {
"@typescript-eslint/no-floating-promises": "error",
"@typescript-eslint/no-misused-promises": "error",
"no-async-promise-executor": "error"
}
}
no-floating-promises flags the onSave example. no-misused-promises flags async functions passed where a void-returning callback is expected, such as the forEach(async ...) case. For loops, either await Promise.allSettled(items.map(...)) or a for...of with await gives the promises an owner.
3. Treat the global handler as telemetry, not recovery
A global rejection handler is worth having, as a last line of reporting. It is not a place to fix anything.
// Browser
window.addEventListener('unhandledrejection', (event) => {
const err = event.reason instanceof Error ? event.reason : new Error(String(event.reason));
reportError(err, { source: 'unhandledrejection' });
// event.preventDefault() would only silence the console. It fixes nothing.
});
// Node
process.on('unhandledRejection', (reason) => {
logger.fatal({ err: reason }, 'unhandled rejection');
// The process is in an unknown state: log, flush, exit. Don't keep serving traffic.
flushLogsAndExit(1);
});
On the server, a handler that logs and carries on turns a loud crash into silent corruption, which is a worse failure. One related habit makes these reports useful: always reject with an Error. Promise.reject('failed') carries no stack trace, and a stack-less rejection is exactly the kind of event that sat untriaged in our tracker.
Key takeaway
Promises made errors routable. They did not make routing them mandatory. Every .then() creates another promise that can fail alone, every Promise.all decides what a partial failure means whether or not you meant it to, and a rejection with no owner becomes either a crash or, in the browser, a spinner that never stops.
The senior instinct is to ask two questions of every asynchronous call. First: who owns this promise's rejection? Second, for every batch: what should the user and the server see when only some of it succeeds? A rejection nobody handles is a decision made by omission.
What to audit this week
# async callbacks passed to forEach: the promises are never awaited
grep -rnE "\.forEach\(async" src/
# async executors: a throw inside never rejects the outer promise
grep -rnE "new Promise\(async" src/
# every Promise.all: ask what a partial failure should mean here
grep -rn "Promise.all(" src/
# promise-returning calls inside try blocks without await
grep -rnE "return (fetch|api\.)" src/ | grep -v "await"
Then switch on no-floating-promises and read the first page of results. Each hit is a rejection with no owner, and each is cheaper to fix now than to find through a duplicated billing record.




Top comments (2)
The loadUser one slips past that lint config. I put it in a file with exactly those three rules on typescript-eslint 8.73 and it passes clean, since the promise is returned so it isn't floating. Adding
"@typescript-eslint/return-await": ["error", "in-try-catch"]flags line 5 ("Returning an awaited promise is required in this context"), and it's type-aware too so it fits the same setup.The duplicates on retry are the nastiest part of this bug. Besides Promise.allSettled, an idempotency key per Save attempt on the server side saves you here: the second click then replays the same writes instead of creating new versions and sending a second round of emails.