Ref count misassumption #1631
Send to my agent- I've validated the bug against the latest version of DB packages
Describe the bug A clear and concise description of what the bug is.
We are occasionally seeing our eagerly loaded collections cleared, but they will retain a ready state.
To Reproduce Steps to reproduce the behavior: I'm new to the codebase, so I don't have a comprehensive understanding of how everything works. This has been intermittent for us, but I believe what is happening is:
- Subscribers to the underlying collection query unsub to where there are no subs
cleanupQueryIfIdleruns and sees that there is still arefcountof1since when you create aneagercollection this code runs.queryRefCounts.set( hashedQueryKey, (queryRefCounts.get(hashedQueryKey) || 0) + 1, )- Since there is a ref count and no listeners, db is removing the data from the collection under the assumption that this will prevent memory leaks.
Even if refcount > 0, we treat hasListeners as authoritative to prevent leaks. This can happen if subscriptions are GC'd without calling unloadSubset.
But refcount can also be 1 if you created the collection as an eager collection
- But for us this somehow leads to
collection.status = 'ready'andcollection.size = 0
Expected behavior A clear and concise description of what you expected to happen.
I don't expect the collection to clear like this after sitting idle
Screenshots If applicable, add screenshots to help explain your problem.
OS: [e.g. iOS] Tahoe 26.5 Browser [e.g. chrome, safari] Brave 1.90.124 (Official Build) (arm64) Chromium: 148.0.7778.179 Smartphone (please complete the following information): N/A Additional context Add any other context about the problem here.
If it would be helpful, I had AI write up an explanation as well of what the suspected issue is. This may make more sense https://gist.github.com/willbowdler-cc/3448aba0e8fd554f6c33c5fdd7cd80e1
tannerlinsley closed this
wc
Sign in to join this conversation.
Confirming this against
@tanstack/query-db-collection@1.2.7, with a deterministic repro — it isn't intermittent, it's guaranteed for everyeagercollection. The only reason it looks intermittent is that it needs thegcTimetimer to fire, and the defaultgcTimeis 5 minutes.The chain is exactly as described above:
syncModedefaults toeager(query.ts:698).createQueryFromOpts({}), which sets refcount = 1 (query.ts:1389).unloadSubset: syncMode === 'eager' ? undefined : unloadSubset(query.ts:1957) — the only decrementer is disabled, so the refcount can never return to 0.grep queryRefCounts query.tsconfirmsunloadSubsetis the sole decrement site.unsubscribeFromQueries()drops the observer's listeners.gcTimetimer removes the query →cleanupQueryIfIdleseesrefcount=1, hasListeners=false, concludes a subscription was GC'd withoutunloadSubset, warns, and clears the collection.So the "invariant violation" branch is unreachable-by-design in the library's own default mode.
Repro#
gcTime: 50only compresses the wait; with the default 5 minutes the same thing happens, just later.Result#
Two things worth separating:
sizegoes 3 → 0.statusremains'ready'throughout, so a consumer sees neither a loading state nor an error — just a collection that is confidently empty. In an app this is a screen you navigate away from and back to that renders blank forever.Notes#
1.2.9; I diffedquery.ts:1770-1815between 1.2.7 and 1.2.9 and the cleanup path is byte-identical.syncMode: 'on-demand'avoids it (the increment/decrement pair is intact there), but it isn't a workaround for eager users: on-demand only loads vialoadSubset, so a plain subscriber getssize=0and no fetch at all. With a staticqueryKeyit also appends serialized predicates to the key (query.ts:1220), giving one cache entry and one fullqueryFnrun per distinct predicate shape.gcTime: Infinityper collection is the workaround we've adopted, since these collections are session-lived singletons anyway.A minimal fix would be to make the eager base query's refcount not participate in the idle check — e.g. record the eager query separately, or have
cleanupQueryIfIdleskip the warn-and-clear whensyncMode === 'eager'and the refcount equals the one implicit eager reference.