@@ -91,11 +91,11 @@ indefinitely) or upon process exit (more convenient for scripts).
91
91
92
92
## Event: 'uncaughtException'
93
93
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 .
97
97
98
- Example of listening for ` 'uncaughtException' ` :
98
+ For example :
99
99
100
100
``` js
101
101
process .on (' uncaughtException' , (err ) => {
@@ -111,26 +111,27 @@ nonexistentFunc();
111
111
console .log (' This will not run.' );
112
112
```
113
113
114
- Note that ` 'uncaughtException' ` is a very crude mechanism for exception
115
- handling.
114
+ ### Warning: Using ` 'uncaughtException' ` correctly
116
115
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.
120
122
121
123
Exceptions thrown from within the event handler will not be caught. Instead the
122
124
process will exit with a non zero exit code and the stack trace will be printed.
123
125
This is to avoid infinite recursion.
124
126
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.
127
130
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' ` .
134
135
135
136
## Event: 'unhandledRejection'
136
137
0 commit comments