UseQuery in Tanstack Router (Solid) hangs forever

[ldhwaddell]

Which project does this relate to?

Router

Describe the bug

In a solid based Tanstack router or start app, using useQuery outside of a route loader causes the browser to stay in loading state even once data has finished loading.

I have also tested this with a setupRouterSsrQueryIntegration function that mirrors the React one and has the same issues (test-ssr-query-integration.tsx).

Your Example Website or App

https://github.com/ldhwaddell/tanstack-solid-router-query

Steps to Reproduce the Bug or Issue

1. Clone the repo above
2. Run bun i
3. Run bun dev and visit localhost:3000

Expected behavior

The browser will indicate that it has finished loading once the data populates on screen.

Screenshots or Videos

Screen.Recording.2025-09-01.at.6.20.40.PM.mov

Platform

• Router / Start Version: 1.131.31
• OS: Mac
• Browser: chrome, safari
• Browser Version: 140.0.7339.77
• Bundler: vite
• Bundler Version: 7.1.4

Additional context

I recognize this may have to do with how Tanstack Query works under the hood in Solid. I thought it best to report the issue here rather than the Query repo, as the Query lib is still working as expected - the router is having the trouble.

[brenelz]

Yeah i think the tanstack start (solid) plus query needs more work

[brenelz]

I believe if you are just using router you should set it up like this

https://github.com/TanStack/router/blob/alpha/examples/solid/basic-solid-query-file-based/src/main.tsx

[ldhwaddell]

Yeah I think with just router it is ok, but I'm trying to get it working with Start. Seems doing ensureQueryClient on route beforeLoad works if you add it to context after, but aside from that it seems to be having some issues.

Would love to look into it more. Any ideas where to start?

[simllll]

I'm running into a simliar issue, can you check if the root is the same:

• find route-core/dist/{cjs,esm}/ssr-server.js
• search for crossSerializeStream(...) (around line 80)
• there are two function params: onDone& onError, change them to:

onDone: () => {
            console.log('crossSerializeStream onDone');
            p.resolve("")
        },
        onError: (err) => {
            console.log('crossSerializeStream onError', err);
            p.reject(err)
        }

run your server agina, and check if you ever see a consoel log for onDone or onError.

I think the issue is that the ondone handler is never called, not sure why .. but I'm about to open another bug report to get ro the root of this ;)

[CiskaLV]

Ye I tried to check and the onDone is never called same with the onError im using everything latest 1.131.47 for router and start and @tanstack/solid-query 5.89.0

Edit: When i first setup the example it had @tanstack/solid-start@1.121.3 and that worked with out any errors and actually loaded

[Dillpickleschmidt]

Workaround: Custom Hook Using QueryObserver

So you don't spend 24 hours banging your head against a wall with this issue (like I did), here's a working solution.

Something about TanStack Query's useQuery doesn't signal SSR completion properly. You can work around this by creating a custom hook that uses useQuery's internal QueryObserver on the server, and the original useQuery on the client:

export function useCustomQuery<TData>(
  options: () => SolidQueryOptions<TData>,
): UseQueryResult<TData, DefaultError> {
  const queryClient = useQueryClient()

  return createIsomorphicFn()
    .server(function (queryClient: QueryClient, options) {
      const resolvedOptions = options()
      const observer = new QueryObserver(queryClient, resolvedOptions)

      // Check if data is already available synchronously
      const cachedData = queryClient.getQueryData(resolvedOptions.queryKey)
      const hasCachedData = cachedData !== undefined

      // Only use createResource if data is not cached (for Suspense integration)
      const [data] = hasCachedData
        ? [() => cachedData as TData]
        : createResource(() => queryClient.ensureQueryData(resolvedOptions))

      // Proxy to get fresh snapshot on every property access
      return new Proxy({} as UseQueryResult<TData, DefaultError>, {
        get(_target, prop) {
          const result = observer.getOptimisticResult(resolvedOptions)

          if (prop === "data") {
            // If observer has placeholderData, use it (avoid Suspense)
            if (result.data !== undefined) {
              return result.data
            }
            // Otherwise use resource (triggers Suspense if pending)
            return data()
          }

          return result[prop as keyof typeof result]
        },
      })
    })
    .client(function (_queryClient: QueryClient, options) {
      return useQuery(options)
    })(queryClient, options) as UseQueryResult<TData, DefaultError>
}

EDIT 10/2: updated to make options a function to keep it reactive to changes

Important: If you're deferring queries from the server without awaiting them (i.e. with prefetchQuery), configure your router to dehydrate pending queries (idk why shouldDehydrateQuery isn't in the docs but you'll need it to stream queries that are still pending--i.e. requested but not resolved before the page is sent):

// router.tsx
const router = createTanStackRouter({
  routeTree,
  context: { queryClient },
  dehydrate: () => ({
    queryClientState: dehydrate(queryClient, {
      shouldDehydrateQuery: () => true, // Include all queries (even pending)
    }),
  }),
  hydrate: (dehydrated) => {
    hydrate(queryClient, dehydrated.queryClientState)
  },
})

Usage:

// Route loader - prefetch without awaiting
loader: ({ context }) => {
  context.queryClient.prefetchQuery(myQueryOptions)
}

// Component - use like normal useQuery
function MyComponent() {
  const query = useCustomQuery(() => myQueryOptions)
  return <div>{query.data}</div>
}

This gives you:

• ✅ No hanging spinner
• ✅ Single fetch (server-initiated, client-hydrated)
• ✅ Full cache reactivity
• ✅ Identical API to useQuery
• ✅ Suspense works fine with the createResource that we added to the hook ourselves.

The server uses the same QueryObserver.getOptimisticResult() that useQuery uses internally.

Edit: I'm not expert in any of this but it seems to work from my initial testing. Due to being unfamiliar with the inner-workings of TanStack Query and not thoroughly testing beyond my own needs, I may be neglecting some edge cases. YMMV.

[Dillpickleschmidt]

Here's a test I ran that you can try yourself to confirm that deferred loading is working. It tests 3 things, an instant response in the server, a fast response (100ms), and a slow response (10s). This should ensure that you get the first 2 responses in the initial HTML from the server, and that the slow response streams in from the initial request. I have no infinite browser tab loading spinner with this custom hook.
Tested in @tanstack/solid-start": "1.128.1" and @tanstack/solid-query": "5.90.3"

tanstack-start-query-test.txt

[brenelz]

I wonder would this pr fix things or does it still have that issue?

#5310

[brenelz]

I've narrowed it down to this release. TanStack/query@v5.85.4...v5.85.5

If you pin your version to 5.85.4 it seems to not get hung up

[brenelz]

Actually if you use the latest version 5.90.3 and configure your queryClient like this it seems to work?

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      experimental_prefetchInRender: true,
    },
  },
});