Firestore iOS 12.x: acknowledged write is resent forever, blocks the whole mutation queue (reads/listeners keep working)

Open
#17,073 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
43/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Active
Tech stack
cpp, ios
Domain
databases

Research direction

Start by tracing Firestore’s iOS write stream and local mutation queue acknowledgement handling; the report names no source files or tests, so first locate the code paths for persisting an acknowledged mutation. Check how persistence errors are handled and whether they can leave the acknowledged head mutation queued for replay. Done means reproducing the repeated accepted write, identifying the acknowledgement failure, and adding a regression test that verifies the queue drains.

Written by the indexing model from the issue text.

Description

api: firestore
Description

Since we upgraded from Firebase iOS SDK 11.13 to 12.19.0 (via FlutterFire cloud_firestore 6.10.0, invertase precompiled FirebaseFirestore 12.19.0), a part of our iOS users (about 5–10% of active iOS users per day) end up with a Firestore write queue that never drains:

  • get(source: .server) and snapshot listeners keep working (server snapshots arrive).
  • Every new write stays pending forever (hasPendingWrites == true, waitForPendingWrites never completes), for days, across app restarts, network changes and disableNetwork/enableNetwork.
  • Only terminate() + clearPersistence() fixes it (we now do this automatically; the same devices can get stuck again later).

We enabled Firestore Data Access audit logs (DATA_WRITE) for one hour to see what the server receives. For the stuck devices:

  • The device sends the same write again and again, about every 2–3 seconds (e.g. one device: 912 identical Firestore.Write requests in 37 minutes, same document, same updateMask, precondition exists: true).
  • The server accepts every one of them (no error status in the audit entry, granted: true; the document's updateTime advances with every request).
  • The written values are old: they are from the day the device got stuck (e.g. lastCheckedDate from 8 days before). So it is the original queued mutation being replayed, not a new write.
  • All writes queued behind it never reach the server.

So the server acknowledges the head mutation, but the client apparently never processes that acknowledgement, reconnects the write stream and resends the same batch, forever.

Observations:

  • Only seen with SDK 12.x (grpc-c++ 1.69.0 user agent). The first stuck entries in our data appear exactly when our SDK 12 release went out; we had no such reports on 11.13.
  • Not tied to one document type: the stuck head was a user document update (field-mask update of a nested map) on most devices, a setData of a new document in another collection on others.
  • iOS 18, 26 and 27 affected; all iPhone models.
  • On 11.13 we had a different issue: crashes "Failed to open DB … LOCK: Operation not permitted" / "No space left on device" in LevelDB. Our guess (unverified) is that persisting the acknowledgement in the local cache fails and 12.x retries instead of aborting.
Reproducing the issue

We could not reproduce it on our own devices yet. We can share anonymised audit log entries and client-side diagnostics (queue size, pending age, probe results) if useful.

Firebase SDK Version

12.19.0

Xcode Version

27.2

Installation Method

CocoaPods

Firebase Product(s)

Firestore

Targeted Platforms

iOS

Relevant Log Output

If using Swift Package Manager, the project's Package.resolved
Expand Package.resolved snippet

Replace this line with the contents of your Package.resolved.

If using CocoaPods, the project's Podfile.lock
Expand Podfile.lock snippet

Replace this line with the contents of your Podfile.lock!

Dominant language
C++
Stars
7k
Forks
1.8k
Avg merge
1d 1h
Merged PRs (30d)
70

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from firebase/firebase-ios-sdk

All issues in firebase/firebase-ios-sdk

Similar issues

More C++ issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.