I'm building an Android task manager (ROCIs Tasks) with Flutter. The app uses an offline-first architecture: tasks live in Hive locally and sync to Firestore when online.
Users reported a maddening bug — they'd tap to complete a task, the checkbox would animate, and then... it would snap back to incomplete. Here's what was happening and how I fixed it.
The Race Condition
The app listens to a Firestore stream for real-time updates:
_tasksSubscription = _firestoreService.getActiveTasksStream().listen(
(events) async {
for (final event in events) {
final cloudTask = event.task;
// process cloud task...
}
},
);
When a user toggles a task, the app:
- Updates the local Hive store immediately
- Fires notifyListeners() so the UI updates
- Sends the write to Firestore asynchronously The problem: the Firestore query filters isCompleted == false. The moment the write reaches Firestore, the task disappears from the stream — which emits a removed event. Meanwhile, the Firestore write hasn't fully propagated, so the snapshot data is stale. The listener processes the stale snapshot, overwrites the local state, and the UI reverts. Here's the timeline: User taps "complete" → Local Hive: isCompleted = true ✓ → UI updates ✓ → Firestore write sent (async) → Firestore stream emits: task removed from "active" query → Listener processes stale snapshot: isCompleted = false → Overwrites local Hive with false ✗ → UI reverts ✗ The entire round-trip happens in milliseconds. The user sees a flash of completion followed by an instant revert. The Fix: _pendingLocalWrites Guard I added a map that tracks recently toggled tasks and their intended state: final Map _pendingLocalWrites = {}; When a task is toggled, I record the intended state before writing to Firestore: Future toggleTaskCompletion(Task task) async { task.isCompleted = !task.isCompleted; task.completedAt = task.isCompleted ? DateTime.now() : null; // Record the intended state so the Firestore stream doesn't revert it _pendingLocalWrites[task.id] = task.isCompleted; notifyListeners(); await _source.addTask(task); _firestoreService.updateTask(task).catchError((e, s) { _errorHandlingService.logError(e, s, reason: 'Background cloud updateTask failed'); }).whenComplete(() { // Allow stream to handle this task again after Firestore write settles Future.delayed(const Duration(seconds: 3), () { _pendingLocalWrites.remove(task.id); }); }); } In the stream listener, I check the guard before processing each event: final pendingState = _pendingLocalWrites[cloudTask.id]; if (pendingState != null) { // We recently toggled this task — don't let stale data revert it if (event.type == SyncEventType.removed && pendingState) { // We just completed this task — the removed event is expected. // Update Hive to reflect completion from the latest snapshot. final (latestTask, isMissing) = await _firestoreService.fetchTaskById(cloudTask.id); if (latestTask != null && latestTask.isCompleted) { await _source.addTask(latestTask); await _cancelTaskNotificationsById(latestTask.id); needsUpdate = true; } continue; } if (event.type != SyncEventType.removed && !pendingState) { // We just uncompleted this task — ignore the stale cloud event. continue; } } After 3 seconds (enough for Firestore to propagate), the guard is removed and normal stream processing resumes. Why 3 Seconds? Firestore writes typically propagate in 100-500ms. I used 3 seconds as a conservative buffer that covers:
- Slow network connections
- Firestore replication lag under load
- The stream batching multiple events It's a tradeoff — during those 3 seconds, genuine cloud updates to that task from other devices are also suppressed. For a single-user task manager, that's acceptable. For a collaborative app, you'd want a more sophisticated conflict resolution strategy. Key Takeaways
- Firestore streams are great, but they're not instant. The gap between a local write and the stream reflecting it is a race condition window.
- Offline-first needs local-first UI updates. Updating Hive before sending to Firestore ensures the UI never feels laggy. The stream is for background sync, not for driving the UI.
- Simple guard maps work. You don't need a full state machine or optimistic concurrency control for most cases. A Map with a TTL is enough.
4. Test with bad network conditions. This bug was invisible on fast WiFi. It appeared on cellular with 200ms+ latency.
If you're building offline-first Flutter apps with Firestore, this pattern is worth knowing. The full app is in open beta on the Play Store — happy to answer questions about the architecture.
If you have an idea on how to optimize the process, I would love to know!
