fix(query-core): ensure query refetches on mount/retry when status is error (#9728)

[xiangnuans]

error (#9728)

🎯 Changes

• Modified shouldFetchOn in packages/query-core/src/queryObserver.ts:
  • Added a check for query.state.status === 'error'.
  • This ensures that when a component mounts or explicitly requests a refetch (e.g. refetchOnWindowFocus, refetchOnMount, or manual retry via ErrorBoundary), it will trigger a fetch if the query is in an error state, even if the data is technically considered "fresh" (not stale) due to staleTime: Infinity.
• Added regression test in packages/react-query/src/__tests__/issue-9728.test.tsx to reproduce the issue and verify the fix.

✅ Checklist

• I have followed the steps in the Contributing guide.
• I have tested this code locally with pnpm run test:pr.

🚀 Release Impact

• This change affects published code, and I have generated a changeset.
• This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

• Bug Fixes

  • Queries now refetch on mount or retry when in an error state, even if existing data is not stale, when refetch policy permits.

• Tests

  • Added test coverage for error state refetch behavior with error boundaries.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[changeset-bot]

🦋 Changeset detected

Latest commit: d10cca3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 19 packages

Name	Type
@tanstack/query-core	Patch
@tanstack/angular-query-experimental	Patch
@tanstack/query-async-storage-persister	Patch
@tanstack/query-broadcast-client-experimental	Patch
@tanstack/query-persist-client-core	Patch
@tanstack/query-sync-storage-persister	Patch
@tanstack/react-query	Patch
@tanstack/solid-query	Patch
@tanstack/svelte-query	Patch
@tanstack/vue-query	Patch
@tanstack/angular-query-persist-client	Patch
@tanstack/react-query-persist-client	Patch
@tanstack/solid-query-persist-client	Patch
@tanstack/svelte-query-persist-client	Patch
@tanstack/react-query-devtools	Patch
@tanstack/react-query-next-experimental	Patch
@tanstack/solid-query-devtools	Patch
@tanstack/svelte-query-devtools	Patch
@tanstack/vue-query-devtools	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Walkthrough

This PR patches @tanstack/query-core to ensure queries refetch on mount or retry when in an error state, even if existing data is not stale. The fix modifies the shouldFetchOn logic in queryObserver to treat error status as a trigger for fetching, alongside the existing stale-based logic, and includes a comprehensive test case validating the behavior.

Changes

Cohort / File(s)	Summary
Changeset documentation .changeset/open-keys-create.md	New changeset entry documenting patch-level version bump and fix for refetch-on-mount behavior with error states.
Query observer error-state handling packages/query-core/src/queryObserver.ts	Modified shouldFetchOn condition to treat queries with status: 'error' as candidates for fetching when refetch policy enables it, in addition to stale-based checks.
Test for issue 9728 packages/react-query/src/__tests__/issue-9728.test.tsx	New test file validating error-state refetch behavior with QueryErrorResetBoundary, error boundary, and remount cycles; verifies queries fetch successfully after error recovery.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• The core logic change in queryObserver.ts is a single-condition addition; verify the error-state check integrates correctly with existing stale logic.
• The test file provides good coverage but requires understanding of error boundary, QueryErrorResetBoundary, and Suspense interaction patterns.

Suggested labels

package: query-core, package: react-query

Suggested reviewers

• TkDodo

Poem

🐰 A query in error now hops with new flair,
Refetching on mount without a care—
No stale-data walls can hold it back,
Fresh data flows along the track! ✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main fix: ensuring queries refetch on mount/retry when status is error, directly addressing issue #9728.
Description check	✅ Passed	The pull request description is mostly complete and follows the template structure with clear explanations of changes, a filled checklist, and release impact selections.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

.changeset/open-keys-create.md (1)

1-5: Changeset scope and message look accurate; optionally mention focus/reconnect.

Patch scope to @tanstack/query-core and the summary align with the shouldFetchOn change. Note that the implementation also affects refetch on window focus and reconnect via the same helper, which is fine but not called out here; up to you if you want to spell that out in the note.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between aba3260 and d10cca3.

📒 Files selected for processing (3)

• .changeset/open-keys-create.md (1 hunks)
• packages/query-core/src/queryObserver.ts (1 hunks)
• packages/react-query/src/__tests__/issue-9728.test.tsx (1 hunks)

🧰 Additional context used

🧠 Learnings (3)

📓 Common learnings

Learnt from: sukvvon
Repo: TanStack/query PR: 9892
File: packages/solid-query-persist-client/src/__tests__/PersistQueryClientProvider.test.tsx:331-335
Timestamp: 2025-11-22T09:06:05.219Z
Learning: In TanStack/query test files, when a queryFn contains side effects (e.g., setting flags for test verification), prefer async/await syntax for clarity; when there are no side effects, prefer the .then() pattern for conciseness.

📚 Learning: 2025-11-22T09:06:05.219Z

Learnt from: sukvvon
Repo: TanStack/query PR: 9892
File: packages/solid-query-persist-client/src/__tests__/PersistQueryClientProvider.test.tsx:331-335
Timestamp: 2025-11-22T09:06:05.219Z
Learning: In TanStack/query test files, when a queryFn contains side effects (e.g., setting flags for test verification), prefer async/await syntax for clarity; when there are no side effects, prefer the .then() pattern for conciseness.

Applied to files:

• packages/react-query/src/__tests__/issue-9728.test.tsx

📚 Learning: 2025-09-02T17:57:33.184Z

Learnt from: TkDodo
Repo: TanStack/query PR: 9612
File: packages/query-async-storage-persister/src/asyncThrottle.ts:0-0
Timestamp: 2025-09-02T17:57:33.184Z
Learning: When importing from tanstack/query-core in other TanStack Query packages like query-async-storage-persister, a workspace dependency "tanstack/query-core": "workspace:*" needs to be added to the package.json.

Applied to files:

• .changeset/open-keys-create.md

🧬 Code graph analysis (2)

packages/query-core/src/queryObserver.ts (1)

packages/query-core/src/query.ts (1)

• isStale (296-306)

packages/react-query/src/__tests__/issue-9728.test.tsx (1)

packages/query-core/src/queryObserver.ts (1)

• refetch (298-304)

🔇 Additional comments (4)

packages/query-core/src/queryObserver.ts (1)

771-791: Error-aware shouldFetchOn logic matches the intended fix.

Adding query.state.status === 'error' to the fetch predicate ensures that enabled queries with non‑static staleTime will refetch on mount/focus/reconnect when they are in an error state, even if their data isn’t time‑stale, which is exactly what issue 9728 describes. Guarding with value !== false preserves opt‑out via refetchOn* = false, and the existing staleTime === 'static' early return means static queries keep their previous behavior.

packages/react-query/src/__tests__/issue-9728.test.tsx (3)

16-36: Deterministic queryFn and client config nicely model the regression.

Using a vi.fn with a count‑based async implementation plus retry: false and staleTime: Infinity provides a clear, deterministic setup for success→error→success, matching the reported bug scenario.

---

37-78: Error boundary + reset wiring correctly exercises “retry via remount”.

Page throwing via throwOnError: true under ErrorBoundary and QueryErrorResetBoundary, with the Retry button calling resetErrorBoundary, ensures the query is remounted after an error in the presence of existing data—exactly the path the core fix targets.

---

88-107: Assertions cover initial success, error transition, and final successful refetch.

The three phases—first render success (1 call), refetch leading to error UI (2 calls), and Retry leading to “Success 3” (3 calls)—give good coverage for the bug and will regress if shouldFetchOn stops refetching on error with non‑stale data.