Flutter Firestore paginated query drifts when earlier pages update in real time

Answer

Do not re-query all subsequent pages on every change. Merge updates locally in your state layer, refresh the cursor snapshot when the ordering field changes, and use a deterministic order with document ID to recover from skips and duplicates. Re-querying all pages is cost-prohibitive because pagination is snapshot-based.

Confirmed Facts

• startAfterDocument() is evaluated against values captured at the time of the query; it does not track a dynamic window.
• Real-time listeners on page one do not automatically shift page two; changes to documents preceding the cursor do not move the offset.
• If the ordering field of a document used for pagination is modified, the cursor becomes stale relative to the new order.
• Deletions between loads can cause skipped or duplicated items because Firestore has no stable offset.

Likely Explanation

The drift you observe is expected behavior, not a bug. With only a real-time listener on the first page, later pages remain fixed to the cursor values when loaded. To maintain consistency during real-time updates, the application must merge updates locally in the state.

Steps for this case

1. Merge updates locally, do not cascade re-queries

• Keep a real-time listener only on the first page or the visible window.
• Apply snapshot changes to your in-memory list via add, remove duplicates by document ID.
• Fetch subsequent pages with one-time get() calls using limit().

2. Refresh the last-document snapshot when ordering field changes

1. When a document currently stored as a boundary is modified, read its latest version.
2. Replace the stored DocumentSnapshot with the fresh snapshot before the next page fetch.
3. Use a composite order to make ordering stable: primary ordering field plus a unique tie-breaker like document ID.
4. Example order chain: orderBy('createdAt', descending: true).orderBy(FieldPath.documentId).

3. Detect and recover skipped or duplicated documents after deletions

1. When loading page+1, filter results against IDs already present in local state to remove duplicates caused by shifts.
2. If a cursor document is deleted, the startAfterDocument() call will be invalid. Fall back to the previous valid snapshot or re-anchor from the nearest known document.

Verification

Verify with the Firestore Emulator before production use.

// 1. Load page 1 with a real-time listener and page 2 with get()
// 2. Modify ordering field of a doc on page 1
// 3. Confirm page 2 does not auto-shift and cursor remains based on original snapshot
// 4. Delete a doc on page 1 and fetch page 2 again, check for duplicates via ID filtering

Assumption: recent stable Flutter SDK and a mutable ordering field. Uncertainty remains about your exact ordering schema.

One missing diagnostic detail that changes the recommendation: is the ordering field immutable, e.g., server timestamp, or mutable by client writes? If mutable, cursor refresh logic is required; if immutable, drift risk is limited to deletions and duplicate sort values.