TanStack/query · critical

No QueryClient set, use QueryClientProvider to set one

Error message

No QueryClient set, use QueryClientProvider to set one

What it means

Thrown by React's `useQueryClient()` when no `QueryClient` is available: the explicit `queryClient` argument was not passed AND `React.useContext(QueryClientContext)` returned `undefined`. This means there is no `<QueryClientProvider client={...}>` ancestor of the component calling `useQueryClient`. The hook refuses to return `undefined` because every downstream hook (`useQuery`, `useMutation`, etc.) would crash anyway; throwing here points at the real cause.

Source

Thrown at packages/react-query/src/QueryClientProvider.tsx:18

'use client'
import * as React from 'react'

import type { QueryClient } from '@tanstack/query-core'

export const QueryClientContext = React.createContext<QueryClient | undefined>(
  undefined,
)

export const useQueryClient = (queryClient?: QueryClient) => {
  const client = React.useContext(QueryClientContext)

  if (queryClient) {
    return queryClient
  }

  if (!client) {
    throw new Error('No QueryClient set, use QueryClientProvider to set one')
  }

  return client
}

export type QueryClientProviderProps = {
  client: QueryClient
  children?: React.ReactNode
}

export const QueryClientProvider = ({
  client,
  children,
}: QueryClientProviderProps): React.JSX.Element => {
  React.useEffect(() => {
    client.mount()
    return () => {
      client.unmount()

View on GitHub (pinned to 159982c80b)

Solutions

1. Wrap the application root (or at least the subtree containing querying components) with `<QueryClientProvider client={queryClient}>`.
2. In tests/stories, render with the provider: `render(<Component />, { wrapper: ({ children }) => <QueryClientProvider client={qc}>{children}</QueryClientProvider> })`.
3. Pass the client explicitly to bypass context: `useQueryClient(queryClient)` or `useQuery({ queryKey, queryFn, context: ... })`.
4. Verify there is only one copy of `@tanstack/react-query` installed (`npm ls @tanstack/react-query`) so the context singleton matches between provider and consumer.

Example fix

// before - querying component rendered without a provider
function App() {
  const { data } = useQuery({ queryKey: ['todos'], queryFn: fetchTodos })
  return <ul>{data?.map(t => <li key={t.id}>{t.title}</li>)}</ul>
}

// after - wrap with QueryClientProvider
const queryClient = new QueryClient()
function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <Todos />
    </QueryClientProvider>
  )
}

// Ensure the consumer is rendered within a provider
import React, { useContext } from 'react'
import { QueryClientContext } from '@tanstack/react-query'
const hasQueryClient = () => useContext(QueryClientContext) !== undefined
// In a component: if (!hasQueryClient()) throw new Error('wrap me in QueryClientProvider')

import { useContext } from 'react'
import { QueryClientContext, type QueryClient } from '@tanstack/react-query'
function useOptionalQueryClient(): QueryClient | undefined {
  return useContext(QueryClientContext)
}
// consumer: const client = useOptionalQueryClient(); if (!client) return null

let client
try {
  client = useQueryClient()
} catch (e) {
  if (e.message === 'No QueryClient set, use QueryClientProvider to set one') {
    // either render nothing, or pass a fallback client explicitly
    return null
  }
  throw e
}

When it happens

Trigger: Calling `useQueryClient()`, `useQuery`, `useMutation`, `useInfiniteQuery`, etc. in a component rendered outside a `<QueryClientProvider>`. Also when an explicit client is not passed and the context is empty — e.g. the provider was not rendered, was rendered below the consumer, was conditionally skipped, or the consumer is rendered via a portal/inline import that escapes the React tree.

Common situations: Forgot to wrap the app in `<QueryClientProvider client={new QueryClient()}>`; rendered a querying component in a Storybook story, test, or modal portal without the provider; provider placed inside a subtree but the component renders through a React portal whose tree is detached; multiple React copies / context identity mismatch across packages; HMR causing context identity drift.

Related errors

• No QueryClient set, use QueryClientProvider to set one
• No QueryClient set, use QueryClientProvider to set one
• usePiPWindow must be used within a PiPProvider
• No QueryClient was found in Svelte context. Did you forget t

AI-assisted analysis of TanStack/query@159982c80b (2026-08-12). Data as JSON: /api/errors/2cdaff913265a2f9. Report an issue: GitHub.