Catch unhandled errors and promise rejections in your Electron app
You can use this module in both the main process and renderer processes. See Renderer processes for the setup that a renderer needs.
npm install electron-unhandledRequires Electron 44 or later.
import unhandled from 'electron-unhandled';
unhandled();The module must run where it can see the errors, and it must be able to reach the main process. That has two consequences:
- The module has to be bundled into your renderer code, or loaded from a preload script. A
<script type="module">in a page cannot resolve the imports of the module, such aselectronandnode:process. - The context must see the errors of the page. A preload script with
contextIsolationenabled (the Electron default) does not receive errors from the page, sounhandled()in such a preload reports only the errors of the preload itself. SetcontextIsolation: falseto catch the errors of the page, or catch them in the page and send them to the main process yourself.
The handlers are registered by the unhandled() call. They are not injected into windows that are created later, because a page cannot load the module without nodeIntegration. Call unhandled() in the code of each window instead.
An ES module preload script needs sandbox: false, because a sandboxed preload script cannot use ESM imports.
You probably want to call this both in the main process and any renderer processes to catch all possible errors.
Note: At minimum, this function must be called in the main process.
A renderer process that crashes or stops responding is also reported. The reported error has no stack trace of your app, so the dialog and the copied text show the message without a stack trace. Pages that are created after the call are watched.
Type: object
Note: These options can only be specified in the main process.
Type: Function
Default: console.error
Custom logger that receives the error.
Can be useful if you for example integrate with Sentry.
Use it to run your own code for an error, for example to restart the app:
import {app} from 'electron';
import unhandled from 'electron-unhandled';
unhandled({
logger(error) {
console.error(error);
app.relaunch();
app.exit();
}
});Type: (error: Error) => boolean
Default: undefined
Filter errors which should not be logged or shown to the user. Return true to discard the error.
Can be useful if you want to fail silently for classes of unhandled errors like ERR_NETWORK_DISCONNECTED. The error is guaranteed to have at least a name and message property.
import unhandled from 'electron-unhandled';
unhandled({
filter: error => error.message.includes('ERR_NETWORK_DISCONNECTED')
});Type: boolean
Default: Only in production
Present an error dialog to the user.
Type: (message: string) => string
Default: undefined
Function that receives the default message of the error dialog and returns the message to show.
Can be useful to add a prefix, or to translate the message.
import unhandled from 'electron-unhandled';
unhandled({
message: message => `Please contact support: ${message}`
});Type: boolean
Default: true
Show the stack trace of the error in the error dialog and in the text that the Copy Error button copies. When disabled, the button copies the title and the type and message of the error only.
A value that is not an error has no stack trace of your app, so the dialog shows the type and message of the error only.
Type: Function
Default: undefined
When specified, the error dialog will include a Report… button, which when clicked, executes the given function with the error as the first argument.
import unhandled from 'electron-unhandled';
import {openNewGitHubIssue} from 'electron-util';
import {debugInfo} from 'electron-util/main';
unhandled({
reportButton: error => {
openNewGitHubIssue({
user: 'sindresorhus',
repo: 'electron-unhandled',
body: `
## Node.js error stack
\`\`\`
${error.stack}
\`\`\`
## Node.js debug info
${debugInfo()}`
});
}
});Example of how the GitHub issue will look like.
Log an error. This does the same as with caught unhandled errors.
It will use the same options specified in the unhandled() call or the defaults.
import {logError} from 'electron-unhandled';
logError(new Error('🦄'));Type: Error
The error to log.
Type: object
Type: string
Default: ${appName} encountered an error
The text shown at the top of the error dialog. It is passed as the message of the dialog, because macOS does not show a dialog title.
Type: boolean
Default: true, until the showStackTrace option of unhandled() says otherwise
Show the stack trace of the error in the error dialog and in the text that the Copy Error button copies. When disabled, the button copies the title and the type and message of the error only.
- electron-store - Save and load data like user settings, app state, cache, etc
- electron-debug - Adds useful debug features to your Electron app
- electron-context-menu - Context menu for your Electron app
- electron-dl - Simplified file downloads for your Electron app