Error `[QueryCollection] queryClient must be provided.` on Tanstack Start's `beforeLoad`

[chanithecat]

Hi all!

Im getting an error when I try to prefetch a live query in Tanstack Start's lifecycle functions like loader and beforeLoad.

An error occured while server rendering /chats/rhelkg6obiily4yrfwky1bsb:

	[QueryCollection] queryClient must be provided.

QueryClientRequiredError: [QueryCollection] queryClient must be provided.
 at queryCollectionOptions (/home/chani/Documents/projects/chat-demo/node_modules/@tanstack/query-db-collection/src/query.ts:462:11)
 at /home/chani/Documents/projects/chat-demo/src/lib/collections/chat.ts:11:31
	...rest of stack trace

Occurs when I run a prefetch on the beforeLoad

import { createLiveQueryCollection, eq } from '@tanstack/react-db'
import { createFileRoute, useLocation } from '@tanstack/react-router'
import { chatCollection } from '@/lib/collections/chat'

const getChat = (chatId: string) => {
 return createLiveQueryCollection({
 query: (q) =>
 q
 .from({ chat: chatCollection })
 .select(({ chat }) => ({ ...chat }))
 .where(({ chat }) => eq(chat.id, chatId)),
 })
}
export const Route = createFileRoute('/_protected/chats/$chatId')({
 ssr: false,
 beforeLoad({ location, params }) {
 const existingChat = location.state.existingChat
 if (existingChat) {
 getChat(params.chatId).preload()
 }
 },
 component: RouteComponent,
 ssr: false,
})

function RouteComponent() {
 const { state } = useLocation()

 return (
 <div>
 <div>Hello "/_protected/chats/$chatId"! </div>
 <pre>{JSON.stringify(state, null, 2)}</pre>
 </div>
 )
}

Its saying that I didnt provide queryClient in chatCollection in chat.ts even though i did.

// chat.ts
import {
 createCollection,
} from '@tanstack/react-db'
import { queryCollectionOptions } from '@tanstack/query-db-collection'
import { createChat, createChatSchema, getChats } from '@/lib/server/chat'
import { queryClient } from '@/lib/queryClient'

export const chatCollection = createCollection(
 queryCollectionOptions({
 queryClient,
 queryKey: ['chats'],
 queryFn: async () => await getChats({ data: { limit: 24 } }),
 schema: createChatSchema,
 startSync: true,
 getKey: (item) => item.id,
 onInsert: async ({ transaction }) => {
 const newChats = transaction.mutations.map((m) => m.modified)

 await Promise.all(
 newChats.map((chat) =>
 createChat({
 data: { user2Id: chat.user2Id! },
 }),
 ),
 )
 },
 }),
)

export const loadMoreChats = async (lastChatDate: Date) => {
 const newChats = await getChats({
 data: { limit: 8, beforeDate: lastChatDate },
 })

 chatCollection.utils.writeBatch(() => {
 newChats.forEach((chat) => {
 chatCollection.utils.writeInsert(chat)
 })
 })
}

Its working fine in a component but not in the loader. Am i doing something wrong? Im trying to make it a route guard though perhaps this is just bad usage?

Thanks in advance!

[chanithecat]

The error went away after exporting the queryclient in a ts file instead of creating it in the router. I dont get it

[mhornbacher]

Did you test this with SSR? It seems that their docs indicate that the query client is then shared across multiple requests

https://tanstack.com/query/v5/docs/framework/react/guides/ssr

[KyleAMathews]

Resolved through the runtime QueryClient factory guidance in #1667. Request-scoped environments should create or retrieve the collection from request or router context using that scoped QueryClient, rather than constructing a process-global collection. The original report also confirmed that moving QueryClient creation out of router initialization resolved the immediate missing-client error. See the Query Collection guide and RFC #1643.