fix(solid-query): prevent suspense trigger with pre-cached data

[shinseongsu]

When using refetchOnMount: false with pre-cached data, the first setQueryData call would incorrectly trigger a Suspense fallback. This happened because the Proxy handler was calling queryResource() even when cached data was available.

This fix ensures that:

1. The resource resolves immediately when data is already available, regardless of the isLoading state
2. The Proxy handler returns cached data directly when isFetching is false and data exists, avoiding unnecessary resource access

Closes #9883

🎯 Changes

useBaseQuery.ts (line 263): Added || observerResult.data !== undefined condition to resolve the resource immediately when cached data exists, even if isLoading is true

useBaseQuery.ts (line 378-390): Modified the Proxy handler to check isFetching state before accessing queryResource(). When isFetching is false and data exists in either state or observerResult, return it directly without triggering Suspense

suspense.test.tsx: Added test case to verify that Suspense is never triggered when using refetchOnMount: false with pre-cached data, including initial render and subsequent setQueryData calls

result

Jan-19-2026.00-07-02.1.mp4

✅ 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

  • Improved Suspense mode handling to better manage pre-cached query data, preventing unnecessary suspension during data mutations.
  • Enhanced data retrieval logic to prioritize available cached data and optimize loading state detection.

• Tests

  • Added comprehensive test coverage for Suspense mode behavior with pre-cached data and disabled refetch on mount.

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: c58334b

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[coderabbitai]

📝 Walkthrough

Walkthrough

Fixes a bug where mutations with refetchOnMount: false incorrectly trigger suspense when data is already cached. Modifies data retrieval precedence and loading conditions in Solid Query's base hook to prevent unnecessary suspense activation.

Changes

Cohort / File(s)	Summary
Test Addition packages/solid-query/src/__tests__/suspense.test.tsx	Adds test case verifying suspense is not triggered when setQueryData mutates a pre-cached key with refetchOnMount: false, validating both initial render and subsequent mutations.
Core Logic Modification packages/solid-query/src/useBaseQuery.ts	Relaxes server/client resolver loading condition to resolve when observerResult.data exists. Enhances data accessor precedence to check observerResult.data before falling back to queryResource()?.data, using isFetching instead of isLoading for cached data returns.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• fix(core): observing "promise" needs to implicitly observe "data" #9772: Modifies data tracking behavior to prefer observerResult.data and avoid suspense triggers when cached data exists, addressing the same underlying observer behavior.
• fix(solid-query): enable experimental_prefetchInRender by default for… #9822: Updates useBaseQuery.ts server-side render and data-resolution logic with different resolver/data-return strategies on the same file.

Suggested labels

package: solid-query

Suggested reviewers

• TkDodo

Poem

🐰 A hop and a bound through the cache so profound,
No more suspense creeping around!
With data so dear, now perfectly clear,
Mutations dance—no tremors here! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: preventing suspense triggers when using pre-cached data, which is the core issue being fixed.
Linked Issues check	✅ Passed	The PR successfully implements all coding requirements from issue #9883: it prevents suspense triggers with pre-cached data when refetchOnMount is false, modifies the resource resolution logic to check for cached data, and includes a comprehensive test.
Out of Scope Changes check	✅ Passed	All changes are directly related to fixing the suspense trigger bug described in issue #9883. The test addition, resolver logic changes, and proxy handler modifications are all within scope.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

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