Skip to content

Commit 72d29e6

Browse files
committed
doc: improve unhandledException doc copy
Rework the doc a bit to tighten it up, including removing the use of `you`
1 parent 5d7265f commit 72d29e6

File tree

1 file changed

+18
-17
lines changed

1 file changed

+18
-17
lines changed

doc/api/process.markdown

Lines changed: 18 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -91,11 +91,11 @@ indefinitely) or upon process exit (more convenient for scripts).
9191

9292
## Event: 'uncaughtException'
9393

94-
Emitted when an exception bubbles all the way back to the event loop. If a
95-
listener is added for this exception, the default action (which is to print
96-
a stack trace and exit) will not occur.
94+
The `'uncaughtException'` event is emitted when an exception bubbles all the
95+
way back to the event loop. By default, Node.js handles such exceptions by printing the stack trace to stderr and exiting. Adding a handler for the
96+
`'uncaughtException'` event overrides this default behavior.
9797

98-
Example of listening for `'uncaughtException'`:
98+
For example:
9999

100100
```js
101101
process.on('uncaughtException', (err) => {
@@ -111,26 +111,27 @@ nonexistentFunc();
111111
console.log('This will not run.');
112112
```
113113

114-
Note that `'uncaughtException'` is a very crude mechanism for exception
115-
handling.
114+
### Warning: Using `'uncaughtException'` correctly
116115

117-
Do *not* use it as the Node.js equivalent of `On Error Resume Next`. An
118-
unhandled exception means your application - and by extension Node.js itself -
119-
is in an undefined state. Blindly resuming means *anything* could happen.
116+
Note that `'uncaughtException'` is a crude mechanism for exception handling
117+
intended to be used only as a last resort. The event *should not* be used as
118+
an equivalent to `On Error Resume Next`. Unhandled exceptions inherently mean
119+
that an application is in an undefined state. Attempting to resume application
120+
code without properly recovering from the exception can cause additional
121+
unforeseen and unpredictable issues.
120122

121123
Exceptions thrown from within the event handler will not be caught. Instead the
122124
process will exit with a non zero exit code and the stack trace will be printed.
123125
This is to avoid infinite recursion.
124126

125-
Think of resuming as pulling the power cord when you are upgrading your system.
126-
Nine out of ten times nothing happens - but the 10th time, your system is bust.
127+
Attempting to resume normally after an uncaught exception can be similar to
128+
pulling out of the power cord when upgrading a computer -- nine out of ten
129+
times nothing happens - but the 10th time, the system becomes corrupted.
127130

128-
`'uncaughtException'` should be used to perform synchronous cleanup before
129-
shutting down the process. It is not safe to resume normal operation after
130-
`'uncaughtException'`. If you do use it, restart your application after every
131-
unhandled exception!
132-
133-
You have been warned.
131+
The correct use of `'uncaughtException'` is to perform synchronous cleanup
132+
of allocated resources (e.g. file descriptors, handles, etc) before shutting
133+
down the process. It is not safe to resume normal operation after
134+
`'uncaughtException'`.
134135

135136
## Event: 'unhandledRejection'
136137

0 commit comments

Comments
 (0)