fix(solid-query): don't hang async SSR when a disabled query is rendered

[naveentehrpariya]

🎯 Changes

Resolves #10907

A useQuery with enabled: false hangs renderToStringAsync (and SolidStart's async/stream SSR) as soon as the query is rendered.

Root cause: on the server, useBaseQuery forces experimental_prefetchInRender = true, so every observer result carries a .promise. hydratableObserverResult() strips refetch because functions can't be serialized, but it predates experimental_prefetchInRender and doesn't strip promise. The promise therefore ends up in the resolved resource value, and Solid's SSR serializer (seroval) awaits embedded promises — for a disabled query that promise never settles, so serialization (and the render) hangs forever.

I verified this mechanism empirically against the published @tanstack/solid-query@5.101.0 build using the standalone repro from #10907: the resource fetcher actually resolves immediately (isLoading is false for a disabled query) — the hang happens afterwards, during serialization of the resolved value. Stripping promise from hydratableObserverResult() makes renderToStringAsync settle with the expected markup (data=undefined) and a clean hydration script.

Fix: strip promise from the hydratable result alongside refetch. The client rebuilds the result (including its own promise) from the hydrated query state, so nothing is lost.

Also adds the first SSR-path test for solid-query (isServer mocked to true), asserting the resolved result of a disabled query carries neither refetch nor promise — it fails without the fix.

✅ Checklist

• I have followed the steps in the Contributing guide.
• I have tested this code locally with pnpm run test:pr. (solid-query package: 320 tests + typecheck pass, eslint clean)

🚀 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

  • Prevented server-side rendering from hanging by ensuring non-serializable promise-like values aren’t included in SSR hydration data for disabled queries.

• Tests

  • Added server-side tests verifying disabled and enabled queries render expected data and that non-serializable fields are excluded from serialized query state.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 7825e887-9d94-425a-a822-e206bf9a1ad0

📥 Commits

Reviewing files that changed from the base of the PR and between 28fc443 and 6238fa3.

📒 Files selected for processing (1)

• packages/solid-query/src/__tests__/ssr.test.tsx

---

📝 Walkthrough

Walkthrough

Removes the server-side promise field from hydratable observer results to prevent SSR streaming from hanging for disabled queries; adds server-mode tests and a changeset documenting the fix.

Changes

SSR Disabled Query Promise Fix

Layer / File(s)	Summary
SSR Promise Stripping in useBaseQuery packages/solid-query/src/useBaseQuery.ts	hydratableObserverResult sets promise to undefined during server-side serialization to avoid dehydrating non-serializable prefetch promises that can hang SSR.
SSR Disabled Query Test Suite packages/solid-query/src/__tests__/ssr.test.tsx	Adds Vitest tests that mock solid-js/web as server (isServer: true) and assert that disabled and enabled queries on the server do not expose state.refetch or state.promise.
Changeset Release Note .changeset/solid-query-ssr-disabled-hang.md	Documents the SSR hang fix: the promise field is removed from the hydratable observer result to prevent renderToStringAsync from waiting on unresolved prefetch promises.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• TanStack/query#10887: Related tests and discussion around experimental_prefetchInRender and observer result promise behavior.

Poem

A rabbit peeks at server streams,
Snips loose promises from tangled dreams.
Disabled queries no longer stall,
The renderer hops and answers the call. 🐇✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ 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%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically identifies the fix: preventing SSR hangs when a disabled query is rendered in solid-query.
Description check	✅ Passed	The description comprehensively explains the root cause, the fix, testing approach, and follows the template with completed checklist items and changeset confirmation.
Linked Issues check	✅ Passed	The PR fully addresses issue #10907 by stripping the unresolved promise from hydratableObserverResult, preventing SSR hangs for disabled queries and adding comprehensive SSR tests.
Out of Scope Changes check	✅ Passed	All changes are directly related to fixing the SSR hang issue: modifying hydratableObserverResult, adding SSR tests, and documenting the fix in a changeset entry.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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]

🧹 Nitpick comments (1)

packages/solid-query/src/__tests__/ssr.test.tsx (1)

16-44: ⚡ Quick win

Consider adding a complementary test for enabled queries.

The test correctly verifies that disabled queries no longer leak promise during SSR. To ensure the fix doesn't break the normal SSR path, consider adding a second test case that verifies an enabled query (one that actually fetches) still hydrates correctly on the server.

🧪 Suggested additional test case

+  it('resolves an enabled query and hydrates correctly', async () => {
+    const client = new QueryClient()
+    let state: UseQueryResult<string> | undefined
+
+    function Page() {
+      const query = useQuery(() => ({
+        queryKey: ['enabled-ssr'],
+        queryFn: () => Promise.resolve('fetched-data'),
+        enabled: true,
+      }))
+      state = query
+      return <div>data: {String(query.data)}</div>
+    }
+
+    const rendered = render(() => (
+      <QueryClientProvider client={client}>
+        <Page />
+      </QueryClientProvider>
+    ))
+
+    await waitFor(() => rendered.getByText('data: fetched-data'))
+
+    // Enabled queries should still hydrate with data, but without
+    // non-serializable refetch/promise
+    expect(state!.data).toBe('fetched-data')
+    expect(state!.refetch).toBeUndefined()
+    expect(state!.promise).toBeUndefined()
+  })

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/solid-query/src/__tests__/ssr.test.tsx` around lines 16 - 44, Add a
complementary test in the same file that mirrors the disabled-query SSR test but
uses an enabled query to ensure normal SSR/hydration still works: create a new
it(...) that instantiates QueryClient, renders a Page component which calls
useQuery with enabled: true (or omit enabled) and a queryFn resolving to 'data',
capture the returned UseQueryResult in the same state variable, render inside
QueryClientProvider, wait for the rendered output to show 'data: data', and
assert that state!.refetch and state!.promise are present/defined as appropriate
for an enabled query; use the existing symbols QueryClient, QueryClientProvider,
useQuery, Page, rendered, state to locate where to add the test.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@packages/solid-query/src/__tests__/ssr.test.tsx`:
- Around line 16-44: Add a complementary test in the same file that mirrors the
disabled-query SSR test but uses an enabled query to ensure normal SSR/hydration
still works: create a new it(...) that instantiates QueryClient, renders a Page
component which calls useQuery with enabled: true (or omit enabled) and a
queryFn resolving to 'data', capture the returned UseQueryResult in the same
state variable, render inside QueryClientProvider, wait for the rendered output
to show 'data: data', and assert that state!.refetch and state!.promise are
present/defined as appropriate for an enabled query; use the existing symbols
QueryClient, QueryClientProvider, useQuery, Page, rendered, state to locate
where to add the test.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0ea170c7-f883-4758-b472-09181db5c68a

📥 Commits

Reviewing files that changed from the base of the PR and between feb1efd and 28fc443.

📒 Files selected for processing (3)

• .changeset/solid-query-ssr-disabled-hang.md
• packages/solid-query/src/__tests__/ssr.test.tsx
• packages/solid-query/src/useBaseQuery.ts

[naveentehrpariya]

Added a complementary test for enabled queries on the server — it asserts the query resolves with data and that the serialized result still carries neither refetch nor promise.