Handling errors in one place
This guide covers how to catch, in one place, every uncaught exception and unhandled Promise rejection in the app. It uses two events on application: error and unhandledrejection.
Recommended approach
- Put the listeners for both events at the very top of
main.js, and hand both to the same function. They go at the very top because they can't receive exceptions thrown by top-level code that comes before them. - No need to wrap callbacks. Exceptions thrown in event listeners also fire
error, so errors in thesceneconnectcallback or a tap callback reach this function too. - Whether to call
preventDefault()depends on whether your own handling replaces the default log.preventDefault()cancels only the default log line the runtime prints. The exception has already happened, and the interrupted code doesn't resume.
An uncaught exception doesn't make the app exit: the piece of code that threw stops running, and everything else keeps running as usual; see Unhandled exceptions don't make the app exit.
The first error handler
/** @param {unknown} reason */
function report(reason) {
console.error('something went wrong', String(reason));
}
application.addEventListener('error', (e) => {
report(e.error);
e.preventDefault();
});
application.addEventListener('unhandledrejection', (e) => {
report(e.reason);
e.preventDefault();
});
application.addEventListener('sceneconnect', (e) => {
const win = new UIWindow(e.scene);
const page = new UIViewController();
page.view.backgroundColor = 'systemBackground';
win.rootViewController = page;
win.makeKeyAndVisible();
throw new Error('failed while building the interface');
});Effect
- The screen shows a blank view controller. The code before
throwhas already run, so the window is shown as usual. - The console prints
something went wrong Error: failed while building the interface. BecausepreventDefault()was called, there is no default log line starting withUncaught. - The app keeps running.
Verified in the acceptance tests: after a listener throws, the error event is received once, e.error is exactly the thrown object, and the other listeners for the same event run as usual. This code has not been run as a whole in the simulator.
Note: When an
errorlistener itself throws, the runtime doesn't fireerroragain for it; it only prints the default log to the console.
Seeing where the error happened
application.addEventListener('error', (e) => {
console.log('error location', e.filename, e.lineno);
console.log('is it an Error object', e.error instanceof Error);
e.preventDefault();
});
throw new Error('an exception nobody catches');Effect
- The console prints
error location main.jsfollowed by the line number of thethrow. - The console prints
is it an Error object true. - Because
preventDefault()was called, the runtime no longer prints the default error log. Without it, the runtime prints a log at theconsole.errorlevel starting withUncaught.
filename and lineno point to the bundled main.js, not the source files before bundling. To find the failing code, open the bundle output and look at that line.
Note: An exception thrown at the top level of the script stops the rest of
main.js's top-level code from running. Theerrorevent is only a notification and doesn't resume execution. Listeners already registered remain in effect.
Catching unhandled Promise rejections
application.addEventListener('unhandledrejection', (e) => {
console.log('unhandled rejection', String(e.reason));
e.preventDefault();
});
Promise.reject(new Error('a rejection nobody handles'));Effect
- The console prints
unhandled rejection Error: a rejection nobody handles. - Because
preventDefault()was called, the runtime no longer prints the default log. Without it, the runtime prints an error-level log starting withUncaught (in promise), followed by the rejection reason.
Exceptions thrown in an async function that nobody awaits also end up here. A Promise that gets a handler attached shortly after being rejected isn't reported: the runtime schedules the report at the end of the task queue, so attaching a handler with setTimeout(fn, 0) after the rejection is still in time.
See also
error,ErrorEventunhandledrejection,PromiseRejectionEvent- Timers: the timing of
unhandledrejectionreports is related to them