Photo by Chor Hung Tsang on Unsplash

Handling errors is everyday programmer job. This job is done infinite times in daily work. In Dart we can handle it easily with try-catch block. But what will happen if we miss some code? We get for example “red screen of death”.

Typical red screen of death in Flutter.

It’s okay that our code is not always perfect. Every developer do mistakes, but great developer will fix his mistakes.

Great thing is being clear with users. When we’re users of some application, we want to know that something unexpected happend and we can decide to send error logs to developer or not. Error logs will help developers patching errors.

Developers can fix errors, but they need to know what happend and where. In mobile applications development we need tool, that will report invalid application behaviour to the authors. Currently in Flutter we have support for Sentry error tracking and soon to be Firebase Crashlytics support.

What if we don’t want to use Sentry or Crashlytics? What if we could use some generic tool, which won’t be hard to configure and will help catch errors in developoment stage or even in release? A tool that composes email, so user just need to click “Send” or save crash logs in device memory? And here comes Catcher.

Introducing Catcher

Catcher logo.

Catcher is new Flutter plugin which catches and handles errors in Flutter application. Catcher offers multiple report modes and handlers to cooperate with Flutter applications. Catcher is heavily inspired from ACRA.

Catcher report flow is easy to understand (see diagram below). Catcher injects error handlers into your application and catches all unchecked errors. Once it catches error, it creates report and sends it to reporter. Reporter shows information about error and waits for user decision. User can accept or cancel error report. If user accepts error report, then it will be processed by handlers.

You can report your checked errors which were caught in your try catch block.

Catcher also collects information about user device hardware and OS. These data can be accessed without any user permission because there’s no personal informations about user. This data will be very helpful, because sometimes error happen because of device errors, not developer.

Diagram which presents how Catcher works.

Using Catcher

Let’s see a basic example of Catcher. First, we need to install plugin. Go to your pubspec.yaml and add this line:

dependencies:

catcher: ^0.0.8

Next, you need to run packages get command which downloads Catcher and enables it in your project.

Last step is adding this import:

import 'package:catcher/catcher_plugin.dart';

We are ready to use Catcher. Below you can find basic example of Catcher.

main() {

//debug configuration

CatcherOptions debugOptions =

CatcherOptions(DialogReportMode(), [ConsoleHandler()]);

//release configuration

CatcherOptions releaseOptions = CatcherOptions(DialogReportMode(), [

EmailManualHandler(["recipient@email.com"])

]);

//profile configuration

CatcherOptions profileOptions = CatcherOptions(

NotificationReportMode(),

[ConsoleHandler(), ToastHandler()],

handlerTimeout: 10000,

customParameters: {"example": "example_parameter"},

);

//MyApp is root widget

Catcher(MyApp(),

debugConfig: debugOptions,

releaseConfig: releaseOptions,

profileConfig: profileOptions);

}

Normally, when you run your code, your main has only this line: runApp(MyApp()); , which starts application. When you are using Catcher, you won’t specify this line anymore. Instead of this, you need to create Catcher instance with your root widget instance and application profiles.

Catcher allows you to configure 3 application profiles: debug , release and profile . In code above we‘re creating 3 instances of CatcherOptions which describes how Catcher will behave in different modes. Catcher will use debugConfig when the application will run in debug environment, releaseConfig when the application will run in release environment and profileConfig when the application run in ‘profile’ mode.

In each CatcherOptions instance you can configure different report mode and handlers list. Click here to check all configuration parameters of CatcherOptions .

There are 4 report modes:

Silent report mode

Notification report mode

Dialog report mode

Page report mode

There are 6 handler types:

Console handler

Http handler

File handler

Toast handler

Email auto handler

Email manual handler

When you’re creating Catcher instance, it will starts your root widget and listens to any errors that happend in your application. Running code above in debug mode, will show dialog once error happens, where user can make decision. Once user accepts report, it will be processed by console handler and that will simply print report in console.

You can find complete basic example here.