Skip to content
Source
Sign inSign up
TanStack/db

Ref count misassumption #1631

Send to my agent
Closedwillbowdler-cc(GitHub profile, opens in a new tab) opened this issue 3 comments
  • 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:

  1. Subscribers to the underlying collection query unsub to where there are no subs
  2. cleanupQueryIfIdle runs and sees that there is still a refcount of 1 since when you create an eager collection this code runs.
        queryRefCounts.set(
          hashedQueryKey,
          (queryRefCounts.get(hashedQueryKey) || 0) + 1,
        )
  3. 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

  1. But for us this somehow leads to collection.status = 'ready' and collection.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

  1. Confirming this against @tanstack/query-db-collection@1.2.7, with a deterministic repro — it isn't intermittent, it's guaranteed for every eager collection. The only reason it looks intermittent is that it needs the gcTime timer to fire, and the default gcTime is 5 minutes.

    The chain is exactly as described above:

    1. syncMode defaults to eager (query.ts:698).
    2. Eager creates the base query at startup via createQueryFromOpts({}), which sets refcount = 1 (query.ts:1389).
    3. Eager exports unloadSubset: syncMode === 'eager' ? undefined : unloadSubset (query.ts:1957) — the only decrementer is disabled, so the refcount can never return to 0. grep queryRefCounts query.ts confirms unloadSubset is the sole decrement site.
    4. Last subscriber goes → unsubscribeFromQueries() drops the observer's listeners.
    5. The gcTime timer removes the query → cleanupQueryIfIdle sees refcount=1, hasListeners=false, concludes a subscription was GC'd without unloadSubset, warns, and clears the collection.

    So the "invariant violation" branch is unreachable-by-design in the library's own default mode.

    Repro

    import { QueryClient } from '@tanstack/query-core'
    import { createCollection } from '@tanstack/db'
    import { queryCollectionOptions } from '@tanstack/query-db-collection'
    
    const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms))
    
    const trial = async (label: string, extra: Record<string, unknown>) => {
      const queryClient = new QueryClient({ defaultOptions: { queries: { gcTime: 50 } } })
      const c = createCollection(queryCollectionOptions<{ id: string }>({
        id: label, queryClient, queryKey: [label],
        queryFn: async () => [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
        getKey: (r) => r.id, ...extra,
      } as never))
    
      const s1 = c.subscribeChanges(() => {})
      await sleep(200)
      const before = c.size
      s1.unsubscribe()            // route change: subscriberCount -> 0
      await sleep(600)            // let the gcTime timer fire
      const afterCleanup = c.size
    
      const s2 = c.subscribeChanges(() => {})   // navigate back
      await sleep(400)
      console.log(`${label}: before=${before} afterCleanup=${afterCleanup} afterRemount=${c.size} status=${c.status}`)
      s2.unsubscribe()
    }
    
    await trial('default', {})
    await trial('gcTime-Infinity', { gcTime: Infinity })

    gcTime: 50 only compresses the wait; with the default 5 minutes the same thing happens, just later.

    Result

    default:          before=3 afterCleanup=0 afterRemount=0 status=ready
    gcTime-Infinity:  before=3 afterCleanup=3 afterRemount=3 status=ready

    Two things worth separating:

    • The collection is cleared — size goes 3 → 0.
    • It does not recover. Re-subscribing does not refetch; it stays at 0. Meanwhile status remains '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

    • Reproduces identically on 1.2.9; I diffed query.ts:1770-1815 between 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 via loadSubset, so a plain subscriber gets size=0 and no fetch at all. With a static queryKey it also appends serialized predicates to the key (query.ts:1220), giving one cache entry and one full queryFn run per distinct predicate shape.
    • gcTime: Infinity per 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 cleanupQueryIfIdle skip the warn-and-clear when syncMode === 'eager' and the refcount equals the one implicit eager reference.

  2. tannerlinsley closed this

Sign in to join this conversation.