Flutter Web Firestore Cache Issues on Chromebooks

by

Summary

Some Chromebook pupils experience Firestore query times exceeding 30 seconds due to local indexedDB cache corruption or bloat in the Flutter web build of the Firestore SDK. The SDK stores query results and document snapshots in the browser’s indexedDB layer, and on resource-constrained Chromebooks this cache can degrade over time. The query shown retrieves an entire pupil collection, which on a corrupted cache forces the SDK to perform excessive local reads, cache invalidation retries, and network round-trips.

Key takeaway: The problem is not the query itself or the pupil’s account — it is the local Firestore cache state on that specific browser instance.

Root Cause

  • The Flutter web Firestore SDK uses indexedDB to persist query results and document snapshots locally
  • On Chromebooks with limited storage, memory, or after prolonged use without cleanup, the indexedDB cache can become fragmented, bloated, or internally corrupted
  • When a query like collection(keyPupils).get() runs against a degraded cache, the SDK may:
    • Attempt to deserialize a large number of cached documents
    • Hit cache inconsistency errors and fall back to fresh network fetches
    • Retry serialization/deserialization multiple times before returning results
  • Security rules evaluation metadata is also cached alongside documents, and a corrupted cache can cause repeated rule-computation round-trips
  • The issue is pupil-independent because the query targets the schools collection, but the cache degradation is tied to the browser instance, not the auth account

Why This Happens in Real Systems

  • Chromebooks in school environments often have limited disk space and RAM, making indexedDB operations slow as the cache grows
  • The Flutter web build does not aggressively trim or compact the Firestore cache — it relies on the underlying browser storage engine
  • Browser updates, policy restrictions, and network filtering in school environments can cause incomplete cache writes, leaving the indexedDB store in an inconsistent state
  • Powerwashing sometimes helps because it clears browser storage, but indexedDB may persist across certain reset flows or the issue reoccurs because the same degraded environment is recreated

Real-World Impact

  • 30+ second query times make the app unusable during class time
  • Teachers and IT staff at schools perceive the app as unreliable
  • Intermittent reproducibility makes it difficult for developers to diagnose
  • Restarting the Chromebook sometimes helps temporarily but does not guarantee a fix
  • The problem disproportionately affects low-spec Chromebooks with constrained indexedDB performance

How Senior Engineers Fix It

  • Enable persistence explicitly and set a cache size cap. This gives you control over how much data the SDK stores locally:

    await FirebaseFirestore.instance.setPersistenceEnabled(true);
await FirebaseFirestore.instance.clearPersistence();

  • Add a periodic cache cleanup routine that clears the Firestore persistence cache on app startup or after detected slow queries:

    Future resetFirestoreCache() async {
try {
  await FirebaseFirestore.instance.clearPersistence();
} catch (e) {
  print('Failed to clear persistence: $e');
}
}

  • Paginate pupil queries instead of fetching the entire collection:

    QuerySnapshot pupils = await FirebaseFirestore.instance
  .collection('schools')
  .doc(school.schoolId)
  .collection('pupils')
  .limit(50)
  .get();

  • Monitor query performance by wrapping Firestore calls with timing:

    final stopwatch = Stopwatch()..start();
final snapshot = await FirebaseFirestore.instance
  .collection('schools')
  .doc(school.schoolId)
  .collection('pupils')
  .get();
stopwatch.stop();
if (stopwatch.elapsedMilliseconds > 5000) {
// Report or log slow query
log('Slow query detected: ${stopwatch.elapsedMilliseconds}ms');
}

  • Instruct school IT to clear the browser cache via Chrome settings — specifically the indexedDB entries for your Firebase project domain. A more reliable recovery than a full powerwash.

Why Juniors Miss It

  • The query looks simple and works fine in development — local Firestore emulation does not replicate indexedDB cache behavior
  • The intermittent nature (specific devices, sometimes fixed by restart) points developers toward network or account issues rather than local storage
  • Juniors typically do not think about browser storage as a performance bottleneck in a mobile-first Flutter codebase
  • There is no obvious error message — the SDK just returns results slowly, which looks like a latency problem rather than a cache problem
  • Not setting persistence explicitly means the SDK uses default browser behavior, which on constrained devices can be unpredictable

Leave a Comment