Mastering Flutter Exception Handling, Gray Release, and Downgrade Strategies

1. Overview of Flutter Exceptions

Flutter exceptions can be categorized into Dart exceptions, Engine exceptions, and Framework exceptions.

Dart exceptions are further divided into synchronous and asynchronous exceptions, as well as App and Framework exceptions.

Dart synchronous exceptions can be caught with

try-catch

.

Dart asynchronous exceptions require

Future.catchError

.

Flutter provides

Zone.runZoned

to intercept all uncaught exceptions, both sync and async, by using the

onError

callback.

<code>runZoned<Future<Null>>(() async {
  runApp(MyApp());
}, onError: (error, stackTrace) async {
  // Do something for error
});
</code>

Framework exceptions are typically thrown during widget build. The default

ErrorWidget

shows a red screen, which can be overridden.

Developers can register a callback with

FlutterError.onError

to intercept exceptions thrown by the Flutter framework.

<code>FlutterError.onError = (FlutterErrorDetails details) {
  reportError(details.exception, details.stack);
};
</code>

Engine exceptions, such as errors in

libflutter.so

on Android or

Flutter.framework

on iOS, are usually handled by platform crash‑reporting SDKs like Firebase Crashlytics or Bugly.

2. Gray Release Strategy

To ensure stability, a complete gray‑release and downgrade solution is required for online Flutter services.

2.1 Gray Release Configuration

The internal configuration platform defines the following fields for each Flutter page:

key

: the Flutter route.

appkey

: the host app.

minVersion

: minimum effective version.

maxVersion

: maximum effective version.

type

: gray‑release type (e.g., tail‑number, region, device, system, mixed, whitelist).

action

: activation scope (full rollout, no rollout, gray rollout, etc.).

url

: downgrade link, supporting parameter substitution for query strings.

2.2 Backend Distribution and Client Loading

Both cold and hot starts fetch the configuration with up to three retries. A local singleton cache stores the configuration, and a fallback downgrade map is kept to ensure graceful degradation if all retries fail.

2.3 Client Processing

When opening a Flutter page, the client checks the gray‑release configuration. If the page is not covered by gray release, the downgrade URL is fetched and opened via WebView. Most business flows replace H5 with Flutter, so a reliable H5 fallback is always available.

3. Downgrade Solutions

Downgrade mechanisms ensure reliability by switching from Flutter to H5 under certain conditions:

3.1 Non‑gray‑release downgrade

If a page is not covered by a gray‑release configuration, it is downgraded and reported.

3.2 Framework exception downgrade

When a Flutter framework exception is captured, the page is marked for downgrade, a custom

ErrorWidget

notifies the user, and the next entry redirects to H5.

3.3 Engine crash downgrade

Engine crashes cause an app crash; logs are reported and a flag prevents Flutter engine startup on the next app launch, triggering full downgrade.

3.4 Product asset load failure downgrade

Custom engine assets are verified via MD5; if the asset download fails after retries, the engine is not started and all pages are fully downgraded.

3.5 Flutter‑related crash downgrade

Crashes caused by Flutter plugins (native side issues) are also downgraded after checking the navigation stack for Flutter activities or view controllers.

4. Operations Daily Report

The daily report aggregates performance and exception data, providing metrics such as page views (PV), success rate, crash rate and affected users, 300 ms launch rate, downgrade rate, and gray‑release rate.

Below is the flow diagram illustrating dynamic asset loading and downgrade strategy: