DEV Community

Cover image for A production bug in your Flutter app: the hotfix checklist
Overpush
Overpush

Posted on

A production bug in your Flutter app: the hotfix checklist

It's late, the app is live, and a user writes in: "My cart is ₹1,598 but the app wants ₹1,59,800."

When a production bug hits, the panic is usually about what to do first. Here's the checklist I follow, from the first report to the fix on users' phones. Most of the steps are plain Flutter; the shipping step shows both the store route and the over-the-air route.


Before anything breaks: make bugs visible

You can't fix what you can't see. Catch every uncaught error and send it to your crash reporter (Crashlytics, Sentry or your own backend):

import 'dart:ui';
import 'package:flutter/material.dart';

void main() {
  // Errors inside Flutter: build, layout, paint.
  FlutterError.onError = (details) {
    FlutterError.presentError(details);
    reportError(details.exception, details.stack);
  };

  // Everything else: async errors, platform channel errors.
  PlatformDispatcher.instance.onError = (error, stack) {
    reportError(error, stack);
    return true;
  };

  runApp(const MyApp());
}

void reportError(Object error, StackTrace? stack) {
  // FirebaseCrashlytics.instance.recordError(error, stack);
  // or Sentry.captureException(error, stackTrace: stack);
}
Enter fullscreen mode Exit fullscreen mode

Tag every report with the exact build it came from. If you ship over-the-air patches, include the patch number too, otherwise you can't tell "fixed" from "still broken":

final tags = await OverPush.crashTags();
// {overpush_release: 1.4.0+12-…, overpush_patch: 3}
tags.forEach(FirebaseCrashlytics.instance.setCustomKey);
Enter fullscreen mode Exit fullscreen mode

☐ 1. Confirm the scope

Before writing any code, answer three questions:

  • Which versions? Filter your crash dashboard by app version. Is it only the latest release?
  • Which platforms? Android only, iOS only, or both?
  • How many users? One user with a strange device, or everyone who opens the cart?

That tells you how fast you need to move, and whether the bug came with the latest change.


☐ 2. Reproduce it in release mode

A lot of production-only bugs never show up in debug mode. Release builds run without asserts and with tree shaking, and timing is different. Reproduce the bug the way users see it:

flutter run --release
Enter fullscreen mode Exit fullscreen mode

If your release build is obfuscated, turn the stack trace into readable code first:

flutter symbolize -i crash_stack.txt -d build/debug-info/app.android-arm64.symbols
Enter fullscreen mode Exit fullscreen mode

☐ 3. Write the test first, then the smallest fix

Write a test that fails because of the bug. It proves you found the right thing, and it stops the bug from coming back.

test('cart total is shown in rupees, not paise', () {
  final total = CartTotal([
    CartItem('Basmati Rice', paise: 54900, qty: 1),
    CartItem('Toor Dal', paise: 17900, qty: 2),
    CartItem('Desi Ghee', paise: 64900, qty: 1),
    CartItem('Fresh Tomatoes', paise: 4200, qty: 1),
  ]);
  expect(total.label, '₹1,598');
});
Enter fullscreen mode Exit fullscreen mode

Then make the smallest change that makes it pass. A hotfix is not the time to refactor:

- String get label => rupees(paise);
+ String get label => rupees(paise ~/ 100);
Enter fullscreen mode Exit fullscreen mode

☐ 4. Check that it's safe to roll back

Ask one question before shipping: does this fix change data that is saved on the phone or sent to your server?

If the fixed code writes data in a new format and you ever have to roll back, the older code has to be able to read it. Keep fixes backward compatible:

  • Add new fields with defaults rather than renaming old ones.
  • Make your parsing tolerant: an unknown value falls back to a default instead of throwing.
  • Keep your server accepting the old request shape.

☐ 5. Ship it

Option A: through the store

  1. Bump the version in pubspec.yaml.
  2. flutter build appbundle / flutter build ipa.
  3. Upload and wait for review: hours, sometimes days.
  4. Wait for users to update.

If the bug is serious, ask for an expedited review on iOS and combine it with a minimum version check so old versions stop being used.

Option B: over the air

If the app was released with OverPush, a Dart fix doesn't need a new store build:

overpush patch ios          # and/or: overpush patch android
Enter fullscreen mode Exit fullscreen mode

Users get the fix the next time they open the app.


☐ 6. Roll out gradually

Even a one-line fix can surprise you. Send it to a slice of users first:

overpush patch android --rollout-percent 10
Enter fullscreen mode Exit fullscreen mode

Watch your crash dashboard for 30–60 minutes, filtered by the new patch number. If it's clean:

overpush patches rollout 1 --percent 100
Enter fullscreen mode Exit fullscreen mode

If it makes things worse, undo it:

overpush patches revoke 1   # stop patch 1; devices go back to the release code
Enter fullscreen mode Exit fullscreen mode

On the store route, the equivalent is Google Play's staged rollout percentage and App Store phased release.


☐ 7. Verify and close the loop

  • Watch the numbers. The error from step 1 should drop to zero for the new build or patch.
  • Reply to the user who reported it. It takes a minute and turns an angry user into a loyal one.
  • Write three lines for the team: what broke, why, and what stops it from happening again. The regression test from step 3 is usually the answer to the last one.

The checklist

☐ Errors reported, tagged with release (and patch)
☐ 1. Scope: versions, platforms, how many users
☐ 2. Reproduced with flutter run --release
☐ 3. Failing test first, then the smallest fix
☐ 4. Safe to roll back: saved data and API stay compatible
☐ 5. Shipped: store release, or overpush patch
☐ 6. Rolled out to 10% first, then everyone
☐ 7. Verified, user answered, notes written
Enter fullscreen mode Exit fullscreen mode

Save this for the next 11:30 pm bug report. 🔖

What's the worst production bug you've had to hotfix? Tell me in the comments.

Top comments (0)