The reinstall bug almost every Flutter app ships

You can't see it in the simulator. Your testers won't hit it. Your crash reporter won't catch it — because it isn't a crash. It's a returning user quietly losing their app.

The setup. Your app stores data locally (drift, sqflite, Hive, Isar) and syncs to a cloud backend (Supabase, Firebase, your own API). Standard, sensible architecture.

Now a user does something completely ordinary: new phone, or they delete the app to free space and reinstall next week. The OS wipes local storage. Your local database is empty.

They open the app. What happens?

The bug. Most launch logic, stripped down, is:

final hasLocalData = await db.hasAnyData();
if (hasLocalData) goToHome();
else goToOnboarding(); // 👈 the bug

An empty local DB is treated as "new user." So your returning user — whose data is sitting intact in your cloud — gets onboarding or a blank home screen. To them, it looks like your app deleted everything. The data isn't gone, but the experience is indistinguishable from data loss, and that's what they write in the review.

"Easy — if local is empty, pull from cloud." That breaks in four ways, each its own outage:

1. New vs. returning is ambiguous. A genuinely new user also has an empty local DB. Always-pull hammers your backend on every signup; never-pull loses returning users. And after a reinstall the auth session is gone too — you can't even check until they sign in.
2. The encryption key is gone. If the local DB is encrypted, the key lived in secure storage — also wiped. You must recover it before writing a single row. That's a real design decision, not an afterthought.
3. It isn't resumable. A 4,000-record pull dies at 2,200 on hotel wifi. Without a checkpoint, the next launch can't tell "done" from "half-full" — so you lose rows or restart from zero.
4. A failed check silently becomes "new user." A timed-out request falls through to the onboarding path, and a returning user stares at a fresh-install screen. A transient blip must mean "retry," never data loss.

The shape of the real fix is a small state machine, not an if. Resolve the launch from four signals: an interrupted checkpoint → resume; local data present → normal launch; no account → onboarding/sign-in then re-check; local empty + authenticated → probe the cloud cheaply (a manifest), then restore or treat as a legitimately empty account. Then the restore itself: recover the key, pull in cursor-paged batches, upsert (idempotent), checkpoint after every batch, and treat any failure as retryable-into-resume.

None of it is exotic — but every piece is where teams get it subtly wrong, and the failure mode is invisible until it's a one-star review.

I packaged it. I kept rebuilding this across apps, so I extracted it into a small, tested, pure-Dart engine: RestoreKit. Zero Flutter/DB/network deps in the core; your stack plugs in through six interfaces. It ships Supabase, drift, and secure-storage adapters, a runnable demo (wipe the device, watch it restore, interrupt it, hit retry), and 36 tests — including the "interrupted restore resumes with no duplicates" case nobody writes a test for.

It's available now — full source, lifetime updates, one-time license: 👉 https://restorekit.dev

Either way: go check your own app's cold-launch path on an empty database with a signed-in returning user. I'd bet a coffee a good number of you ship this bug right now. 👀

What's the worst "looked like data loss but wasn't" bug you've shipped? I collect these.