Error: No QueryClient set in Next.js App Router despite following Advanced SSR guide.

[veljkoza]

I'm trying to set up React Query in Next.js app router in my NPM workspace. I'm following the official documentation on how to do so.

Providers Setup

// apps/template-1/app/providers.tsx
"use client";
let browserQueryClient: QueryClient | undefined; // Singleton pattern

function getQueryClient() {
  if (isServer) return new QueryClient();
  if (!browserQueryClient) browserQueryClient = new QueryClient();
  return browserQueryClient;
}

export default function Providers({ children }) {
  const queryClient = getQueryClient(); // <-- Potential issue
  return (
    <QueryClientProvider client={queryClient}>
      <ApiProvider http={http}>{children}</ApiProvider>
    </QueryClientProvider>
  );
}

The problematic component is this one:

'use client'
export const SearchFilters = () => {
  const { locationsQueries } = useApiQueries(); // Custom context
  const { data: cities } = locationsQueries.getCities.useQuery(); // Error here
};

SearchFilters is a child node of a server component page.

Error (happens on server side):

Error: No QueryClient set occurs in SearchFilters despite being wrapped in Providers.

Troubleshooting done:

• multiple react query versions -> they are all the same
• different react versions -> same in every package/app
• adding HydrationBoundary to page.tsx and passing queryClient to it

Involved files hirearchy in a monorepo set-up:

.
├── apps/
│   └── template-1/
│       └── app/
│           ├── [domain]/             # Dynamic route segment
│           │   └── page.tsx          # Server component entry point (data fetching)
│           ├── layout.tsx           # Root layout (wraps app with Providers)
│           └── providers.tsx        # Client component with QueryClient setup ❗Problematic
│
├── packages/
│   ├── react-core/                   # Shared React logic
│   │   └── src/
│   │       └── api-provider/
│   │           └── api-provider.tsx # Custom context using React Query ❗Depends on QueryClient
│   │
│   └── template-1-kit/              # UI components
│       └── src/
│           ├── template-renderer.tsx # Server component rendering widgets
│           └── widgets/
│               ├── hero-widget.tsx   # Renders SearchFilters client component
│               └── search-filters.tsx # ❗Where error occurs (uses useQuery)
│
└── # Key Relationships:
    # 1. layout.tsx → providers.tsx (QueryClientProvider)
    # 2. page.tsx → TemplateRenderer → HeroWidget → SearchFilters
    # 3. SearchFilters uses useApiQueries → needs both:
    #    - ApiProvider (from providers.tsx)
    #    - QueryClient (from QueryClientProvider)
    #
    # Critical Issue: Client component tree not properly hydrated despite Providers

[kenorvick]

I'm still processing your exact setup and why you would be receiving the error server side but the first thing that comes to mind to try would be the following:

Further down in the documentation you linked there is a Streaming with Server Components section which gives an example of extracting the creation of the new QueryClient. If you aren't doing streaming you can ignore the dehydrate options but it might be worth trying to extract the makeQueryClient out of the client Provider.

Though you may already be doing this, when you say adding HydrationBoundary to page.tsx and passing queryClient to it, make sure you are using this same makeQueryClient function to create a new instance to pass to the HydrationBoundary in page.tsx.

I'm a little stumped on why you would be receiving this error on the server side unless you weren't creating a new QueryClient instance that you are passing to the Hydration Boundary in page.tsx.

If none of these suggestion work can you post your page.tsx code and the exact error on the server?

[kenorvick]

I don't think it should matter... as long as you have the dehydrate(queryClient) being correctly used but trying out this method of extracting the getQueryClient to a separate file/import outside the provider might send you down a path of figuring it out. Let me know what you find

[veljkoza]

Okay, so I've tried couiple of things.

My full app/providers.tsx:

// In Next.js, this file would be called: app/providers.tsx
"use client"

import { http } from "@/infrastructure/http"
import { makeQueryClient } from "@/lib/make-query-client"
// Since QueryClientProvider relies on useContext under the hood, we have to put 'use client' on top
import { ApiProvider } from "@repo/react-core/src/api-provider/api-provider"
import {
  QueryClient,
  QueryClientProvider,
  isServer,
} from "@tanstack/react-query"



let browserQueryClient: QueryClient | undefined = undefined

export function getQueryClient() {
  if (isServer) {
    // Server: always make a new query client
    return makeQueryClient()
  } else {
    // Browser: make a new query client if we don't already have one
    // This is very important, so we don't re-make a new client if React
    // suspends during the initial render. This may not be needed if we
    // have a suspense boundary BELOW the creation of the query client
    if (!browserQueryClient) browserQueryClient = makeQueryClient()
    return browserQueryClient
  }
}

export default function Providers({ children }: { children: React.ReactNode }) {
  // NOTE: Avoid useState when initializing the query client if you don't
  //       have a suspense boundary between this and the code that may
  //       suspend because React will throw away the client on the initial
  //       render if it suspends and there is no boundary
  const queryClient = getQueryClient()
  return (
    <QueryClientProvider client={queryClient}>
      <ApiProvider http={http}>{children}</ApiProvider>
    </QueryClientProvider>
  )
}

My app/[domain]page.tsx:

import { websitesService } from "@/api"
import { collectionsService } from "@/api/collections.service"
import { listingsService } from "@/api/listings.service"
import { http } from "@/infrastructure/http"
import {
  HydrationBoundary,
  QueryClient,
  dehydrate,
} from "@tanstack/react-query"
import { Template1Renderer } from "template-1-kit"

import { getWebsiteSlugFromDomain } from "@/lib/get-website-slug"
import { makeQueryClient } from "@/lib/make-query-client"

export default async function SiteHomePage({
  params,
}: {
  params: { domain: string }
}) {
  const domain = decodeURIComponent(params.domain)

  const slug = getWebsiteSlugFromDomain(domain)
  if (!slug) return <h1>Slug not present [app/domain/page.tsx]</h1>

  const website = await websitesService.getWebsiteBySlug(slug)

  if (!website)
    return <h1>Website not found [{`${slug}`}] [app/domain/page.tsx]</h1>

  const indexPageId = website.indexPageId
  const indexPage = website.pages.find((page) => page.id === indexPageId)
  console.log("index page", { indexPage })
  if (!indexPage) return <h1>No index page found [app/domain/page.tsx]</h1>

  // TODO: Show notFound here in the future, this is for debugging purposes
  if (!indexPage.visible) return <h1>Page invisible</h1>
  const queryClient = makeQueryClient()
  return (
    <HydrationBoundary queryClient={queryClient}>
      {/* @ts-expect-error Server Component */}
      <Template1Renderer
        type="index"
        website={website}
        http={http}
        // listingsService={listingsService}
        // collectionsService={collectionsService}
      />
    </HydrationBoundary>
  )
}

Will result in the following error (server-side):

⨯ ../../node_modules/@tanstack/react-query/build/modern/QueryClientProvider.cjs (50:0) @ useQueryClient
 ⨯ Error: No QueryClient set, use QueryClientProvider to set one
    at SearchFilters (../../packages/template-1-kit/src/widgets/search-filters.tsx:30:68)
null

packages/template-1-kit/src/widgets/search-filters.tsx:

'use client';

import { FC } from 'react';


import { Input } from 'ui-kit/src/ui/input';
import { useListingFilters } from '../hooks/useListingFilters';
import { RotateCcw, Search } from 'lucide-react';
import {
  ListingFiltersMetadata,
  type ListingPurpose,
  type ListingType,
} from '@repo/domain';

import { useApiQueries } from '@repo/react-core/src/api-provider/api-provider';

export interface SearchFilters {
  city: string;
  district: string;
  propertyType: string;
  structure: string;
  purpose: string;
  priceFrom: string;
  priceTo: string;
  areaFrom: string;
  areaTo: string;
  referenceNumber: string;
}

export const SearchFilters: FC<{
  filtersMetadata?: ListingFiltersMetadata;
}> = ({ filtersMetadata }) => {
  const { filters, onChange, resetFilters } = useListingFilters({
    filtersMetadata,
  });

  const { locationsQueries } = useApiQueries();
  const { data: cities, isLoading } = locationsQueries.getCities.useQuery();

The page.tsx (server component) imports Template1Renderer (server component), which imports SearchFilters (client component)

in SearchFilters I get this server error o.O. Could it have something to do with how Next.js parses files which aren't in the main directory where next.config.js is so it doesn't read directives like use client?
Maybe I'm missing something obvious here

[kenorvick]

Ok this might be a red herring but can you try a couple things for me? I do think there could be another issue like you mentioned at the end but I notice a couple things.

First would be your makeQueryClient is a little bit off. What the docs say to do is to create a completed separate file outside of the client side provider like this:

// app/get-query-client.ts
import {
  isServer,
  QueryClient,
  defaultShouldDehydrateQuery,
} from '@tanstack/react-query'

function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 60 * 1000,
      },
      dehydrate: {
        // include pending queries in dehydration
        shouldDehydrateQuery: (query) =>
          defaultShouldDehydrateQuery(query) ||
          query.state.status === 'pending',
      },
    },
  })
}

let browserQueryClient: QueryClient | undefined = undefined

export function getQueryClient() {
  if (isServer) {
    // Server: always make a new query client
    return makeQueryClient()
  } else {
    // Browser: make a new query client if we don't already have one
    // This is very important, so we don't re-make a new client if React
    // suspends during the initial render. This may not be needed if we
    // have a suspense boundary BELOW the creation of the query client
    if (!browserQueryClient) browserQueryClient = makeQueryClient()
    return browserQueryClient
  }
}

Once you do that you only now have to call const queryClient = getQueryClient(); in both your client and server components. The current setup you have now is a bit odd to me still have the getQueryClient in your providers.tsx

Second thing I noticed is that you have not utilizing <HydrationBoundary state={dehydrate(queryClient)}>. Specifically the dehydrate function. If you are prefetching server side you need to dehydrate the queryClient so that it can rehydrate the QueryCache on the client. This would be my biggest guess on why you are receiving this error on the server side

[veljkoza]

First of all thanks for taking time to respond and try out things with me, it's great!

I've moved out the function into separate file:

// lib/make-query-client.tsx
import {
  QueryClient,
  defaultShouldDehydrateQuery,
  isServer,
} from "@tanstack/react-query"

function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 60 * 1000,
      },
      dehydrate: {
        // include pending queries in dehydration
        shouldDehydrateQuery: (query) =>
          defaultShouldDehydrateQuery(query) ||
          query.state.status === "pending",
      },
    },
  })
}

let browserQueryClient: QueryClient | undefined = undefined

export function getQueryClient() {
  if (isServer) {
    // Server: always make a new query client
    return makeQueryClient()
  } else {
    // Browser: make a new query client if we don't already have one
    // This is very important, so we don't re-make a new client if React
    // suspends during the initial render. This may not be needed if we
    // have a suspense boundary BELOW the creation of the query client
    if (!browserQueryClient) browserQueryClient = makeQueryClient()
    return browserQueryClient
  }
}

Then in page.tsx:

import { websitesService } from "@/api"
import { collectionsService } from "@/api/collections.service"
import { listingsService } from "@/api/listings.service"
import { http } from "@/infrastructure/http"
import {
  HydrationBoundary,
  QueryClient,
  dehydrate,
} from "@tanstack/react-query"
import { Template1Renderer } from "template-1-kit"

import { getWebsiteSlugFromDomain } from "@/lib/get-website-slug"
import { getQueryClient } from "@/lib/make-query-client"

export default async function SiteHomePage({
  params,
}: {
  params: { domain: string }
}) {
  const domain = decodeURIComponent(params.domain)

  const slug = getWebsiteSlugFromDomain(domain)
  if (!slug) return <h1>Slug not present [app/domain/page.tsx]</h1>

  const website = await websitesService.getWebsiteBySlug(slug)

  if (!website)
    return <h1>Website not found [{`${slug}`}] [app/domain/page.tsx]</h1>

  const indexPageId = website.indexPageId
  const indexPage = website.pages.find((page) => page.id === indexPageId)
  console.log("index page", { indexPage })
  if (!indexPage) return <h1>No index page found [app/domain/page.tsx]</h1>

  // TODO: Show notFound here in the future, this is for debugging purposes
  if (!indexPage.visible) return <h1>Page invisible</h1>
  const queryClient = getQueryClient()
  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      {/* @ts-expect-error Server Component */}
      <Template1Renderer
        type="index"
        website={website}
        http={http}
        // listingsService={listingsService}
        // collectionsService={collectionsService}
      />
    </HydrationBoundary>
  )
}

I don't actually need to prefetch anything for now, I just tried to include HydrationBoundary and remove it, although I always get the same:

⨯ ../../node_modules/@tanstack/react-query/build/modern/QueryClientProvider.cjs (50:0) @ useQueryClient
 ⨯ Error: No QueryClient set, use QueryClientProvider to set one
    at SearchFilters (../../packages/template-1-kit/src/widgets/search-filters.tsx:30:68)

I will try to move all code from package into a next.js directory and see if that changes things

[kenorvick]

Hmm this is a fun one. I'm guessing now that that must be it but I feel like with your setup it still should be ok. I'm going to keep thinking on it but let me know what you find!