Scoped mutations queued behind another mutation stay paused while the document is hidden, even with networkMode: 'always'

[malayyka]

Describe the bug

A mutation with a scope.id that is queued behind another mutation in the same scope does not start when the earlier one settles if the document is hidden. It stays isPaused: true until the window regains focus, whatever its networkMode or retry setting. So a browser tab in the background runs the first write of a scope and holds every later one. For example, a user switches tabs while an upload registers two files: the first registers, and the second sits at "pending" until they come back.

The cause is that the scope queue resumes the next mutation through the retryer's pause gate. When a scoped mutation settles, MutationCache.runNext calls continue() on the next paused mutation in the scope. That resolves the retryer's pause only if canContinue() holds:

// packages/query-core/src/retryer.ts
const canContinue = () =>
  focusManager.isFocused() &&
  (config.networkMode === 'always' || onlineManager.isOnline()) &&
  config.canRun()

focusManager.isFocused() is false in a hidden document, so the continue() call is dropped. The mutation then waits for the next focus (or online) event, when QueryClient calls resumePausedMutations().

The focus condition fits the place it was written for: pausing a retry while the page is hidden (// Pause if the document is not visible or when the device is offline). But starting a mutation doesn't check focus. canStart() is canFetch(networkMode) && canRun(), so an unscoped mutation, or the first one in a scope, starts in a hidden tab. Only mutations that waited in a scope queue get the focus condition. That contradicts the docs ("They will be put into a queue and will automatically resume once their time in the queue has come"), and it makes networkMode: 'always' not mean "always" for scoped mutations.

Your minimal, reproducible example

Self-contained Node script (no DOM needed; focusManager.setFocused(false) stands in for a hidden tab):

// repro.mjs — npm i @tanstack/query-core@5.103.2 && node repro.mjs
import { QueryClient, MutationObserver, focusManager } from '@tanstack/query-core'

const client = new QueryClient()
client.mount()
focusManager.setFocused(false) // what a hidden tab reports via visibilitychange

const log = []
const run = (name, ms) =>
  new MutationObserver(client, {
    scope: { id: 'doc-1' },
    networkMode: 'always',
    retry: false,
    mutationFn: async () => {
      log.push(`${name} start`)
      await new Promise((r) => setTimeout(r, ms))
      log.push(`${name} end`)
      return name
    },
  }).mutate()

run('first', 20)
run('second', 20)

await new Promise((r) => setTimeout(r, 500))
const second = client.getMutationCache().getAll()[1]
console.log('after 500 ms hidden:', log, 'second:', second.state.status, 'isPaused =', second.state.isPaused)

focusManager.setFocused(true)
await new Promise((r) => setTimeout(r, 100))
console.log('after focus:', log, 'second:', second.state.status)
client.unmount()

Output on 5.103.2 (also 5.103.1):

after 500 ms hidden: [ 'first start', 'first end' ] second: pending isPaused = true
after focus: [ 'first start', 'first end', 'second start', 'second end' ] second: success

Steps to reproduce

1. Create two mutations with the same scope.id (networkMode: 'always', retry: false).
2. Make the document hidden (switch tabs, or focusManager.setFocused(false)).
3. Call mutate() on both; the first runs to completion.
4. The second stays pending / isPaused: true for as long as the document stays hidden, and starts only on the next focus event.

Expected behavior

When the earlier mutation in its scope settles, a queued scoped mutation starts under the same conditions as an unqueued one. In other words, it waits for the network according to its networkMode, but not for window focus. Focus-gating would still apply to retry delays, as it does today.

A possible fix: separate "resume from the scope queue" from "resume after a retry delay". For example, the continue that runNext triggers could check canStart() (canFetch(networkMode) && canRun()) instead of canContinue(), or canContinue could drop the focus condition when the retryer is paused before its first attempt (failureCount === 0). We're happy to open a PR if either direction sounds right.

How often does this bug happen?

Every time

Platform

Any browser with the default focusManager (reproduced in desktop Chrome with a backgrounded tab), and in Node with focusManager.setFocused(false).

Tanstack Query adapter

react-query (reproduced in query-core directly; not adapter-specific)

TanStack Query version

v5.103.2 (also v5.103.1). The canContinue definition is unchanged on main as of 992c942.

TypeScript version

v7.0.2

Additional context

We currently work around this by not using scope. We serialize writes in an app-owned promise chain per resource and keep retry: false / networkMode: 'always' on those mutations, so none of them ever reaches a retryer pause.