Overview

In Flutter, unhandled exceptions can be thrown from two sides:

• Native Side
• Dart/Flutter Side

User Exceptions

Native Exceptions

When a native exception occurs:

• The app crashes.
• The user needs to reopen the app.
• A crash report is sent to the Instabug dashboard.

Flutter Exceptions

When a Flutter exception occurs:

• The app does not crash; the user can continue their flow.
• The user may reach a point where the app becomes unresponsive (e.g., a button stops working).
• A crash report is sent to the Instabug dashboard.

Crash-Free Sessions Calculation

Crash-Free sessions are calculated as follows:

• Crash Rate = (Total number of crash occurrences) / (Total number of sessions)
• Crash-Free Sessions = 100% - Crash Rate

Common Issue: Low Crash-Free Session Rate on Flutter

A low crash-free session rate can occur because:

• A single session might have multiple Flutter crashes.
• Flutter crashes do not terminate the session, leading to multiple crash reports within the same session.

User Frustration

Users may become frustrated when the app doesn't respond rather than crashing. To mitigate this:

1. Terminate the App (Force a Crash):
   • Use exit(0) to forcefully close the app.
2. Display a Recoverable Error Alert:
   • Show an alert message, such as "A problem happened here," to inform the user of the issue.

Configuring Flutter Exceptions

Flutter exceptions can be customized to be reported as fatal, non-fatal, or completely ignored.

Flutter Crashes as Fatal Crashes

This is done by passing CrashReporting.reportCrash to runZonedGuarded as shown below:

void main() {  
  runZonedGuarded(() {  
    // ...

  // Notice we're using CrashReporting.reportCrash here which reports errors as fatal crashes.  
  }, CrashReporting.reportCrash);  
}

Flutter Crashes as Non-Fatals

This is done by passing CrashReporting.reportHandledCrash to runZonedGuarded as shown below:

void main() {
  runZonedGuarded(() {
    // ...

  // Notice we're using CrashReporting.reportHandledCrash here which reports errors as non-fatal crashes.
  }, CrashReporting.reportHandledCrash);
}

Ignoring Flutter Crashes

This is done by passing a function to runZonedGuarded that doesn’t call CrashReporting.reportCrash or CrashReporting.reportHandledCrash internally as shown below:

void main() {
  runZonedGuarded(() {
    // ...

  // We're passing a custom callback here to handle errors without reporting them to Instabug.
  }, (Object error, StackTrace stackTrace) {
    // Do whatever is needed with the error
    print(error);
    print(stackTrace);
  });
}

Summary of Exception Handling

Native Exceptions

• User Experience: App crashes, user reopens the app.
• Reporting: Native Stacktrace is collected and sent to Instabug.
• Impact: One session can contain only one crash.

Dart/Flutter Exceptions

• User Experience: App does not crash but becomes unresponsive.
• Reporting: Dart Stacktrace is collected and sent to Instabug.
• Impact: One session can contain multiple crashes.

For more details on managing exceptions and improving crash-free sessions, refer to the Instabug documentation.