goldbergyoni / goldbergyoni/nodebestpractices

Outdated: unhandled promise rejections no longer disappear silently since Node.js 15

Open Beginner friendly
#1,360 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Dockerfile
Stars
106k
Forks
10.7k
PR merge metrics
No merged PRs in 30d

Description

**File:** `sections/errorhandling/catchunhandledpromiserejection.md`

### What the article currently says

The One Paragraph Explainer states:

> "unless a developer remembered to add a .catch clause, errors thrown at these places are not handled by the uncaughtException event-handler and disappear"

> "Recent versions of Node added a warning message when an unhandled rejection pops, though this might help to notice when things go wrong but it's obviously not a proper error handling method"

The Blog Quote section also reinforces this:

> "the reality is that a number of modern JavaScript environments won't print errors for any of them"

### What has changed

Since **Node.js 15**, unhandled promise rejections **crash the process by default** (exit code 1). They no longer disappear silently.

This was introduced via **PR #33021** — a semver-major change that resolved the long-standing `DEP0018` deprecation (the same deprecation warning the article dismisses as "not a proper error handling method"). The exact commit is [`3b10f7f`](https://github.com/nodejs/node/commit/3b10f7f933).

**Timeline:**
- Node 6.6 → prints a `DEP0018` deprecation warning, but keeps running (exit code 0)
- **Node 15+** → crashes the process with a full stack trace (exit code 1) ← current default

Reproducible example — on Node 15+ this crashes, it does not silently finish:
```js
async function fetchData() {
throw new Error('something went wrong');
}

fetchData(); // no await, no .catch
console.log('script finished');
```

Output on Node 15+:
```
script finished
/home/user/test.js:2
throw new Error('something went wrong');
^
Error: something went wrong
at fetchData (/home/user/test.js:2:9)
...
```

The old silent behavior can be restored with `--unhandled-rejections=none`.

### Suggested update

- Update the One Paragraph Explainer to clarify the "disappear silently" behavior only applies to **Node < 15**
- Note that `process.on('unhandledRejection')` is still valuable for **custom handling** (structured logging, graceful shutdown, alerting) — but it's no longer the only thing preventing silent failures on modern Node
- Add a Node version compatibility note near the top of the section
- The Blog Quote from James Nelson may also need a caveat since it was written when silent failures were the norm

### References
- [Node.js 15 release notes — Throw on unhandled rejections](https://nodejs.org/en/blog/release/v15.0.0/#throw-on-unhandled-rejections-33021)
- [PR #33021: change default --unhandled-rejections=throw](https://github.com/nodejs/node/pull/33021)
- [Commit 3b10f7f](https://github.com/nodejs/node/commit/3b10f7f933)
- [Node.js CLI docs: --unhandled-rejections flag](https://nodejs.org/api/cli.html#--unhandled-rejectionsmode)

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with sections/errorhandling/catchunhandledpromiserejection.md and compare its claims with the Node.js 15 release notes and CLI documentation linked in the issue. Update the explainer and Blog Quote caveat to distinguish Node versions, explain the continuing use of process.on('unhandledRejection'), and add the requested compatibility note; done means the article no longer describes modern Node.js behavior as silent.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, node.js
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
82/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.