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

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

🚀 Release Impact

• [x] 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[bot]]

🦋 Changeset detected

Latest commit: d10cca30a0233f97831af596b1e59438ab425a9c

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[bot]]

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.}