How to fix No QueryClient set, use QueryClientProvider to set one in React

ReactBEGINNERHIGHUpdated Dec 10, 2025· 102 views

This error occurs when React Query hooks are used without wrapping the component tree in a QueryClientProvider. React Query requires a QueryClient instance to be provided via context to manage caching, queries, and mutations.

Quick fix

Fixes No QueryClient set, use QueryClientProvider to set one

import { QueryClient } from '@tanstack/react-query';

// Create the client instance
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 5, // 5 minutes
      retry: 1,
    },
  },
});

Create a QueryClient instance
Wrap your application with QueryClientProvider
Verify all React Query hooks are within the provider
Check for version conflicts

react — error

$import { QueryClient } from '@tanstack/react-query';
// Create the client instance
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 5, // 5 minutes
      retry: 1,
    },
  },
});
No QueryClient set, use QueryClientProvider to set one

What this error means

This error indicates that you're trying to use React Query hooks (like `useQuery`, `useMutation`, or `useQueryClient`) in a component that isn't wrapped by a QueryClientProvider. React Query relies on React's Context API to make the QueryClient instance accessible throughout your component tree. The QueryClient is the core instance that manages all queries, mutations, caching, and data synchronization in React Query. Without the QueryClientProvider wrapper, hooks cannot access this client instance, resulting in the error. This is a common setup issue that typically occurs when first integrating React Query into an application or when creating new components that use React Query hooks without proper provider configuration.

Typical symptoms

Error thrown when using useQuery, useMutation, or useQueryClient hooks
Application crashes immediately when React Query hooks are called
Error occurs during component mount or initialization
Works in some components but fails in others depending on their location in the tree
Error message: "No QueryClient set, use QueryClientProvider to set one"

Common causes

QueryClientProvider is not wrapping the components that use React Query hooks
QueryClientProvider is placed too low in the component tree (below components using hooks)
Missing QueryClient instance creation before passing to QueryClientProvider
Using React Query hooks outside of the component tree wrapped by QueryClientProvider
Mixing React Query v3 (react-query) and v4+ (@tanstack/react-query) imports causing context conflicts
Multiple QueryClientProvider instances with different contexts in micro-frontend setups

How to fix "No QueryClient set, use QueryClientProvider to set one"

1Create a QueryClient instance

First, import QueryClient and create a new instance. This is typically done at the application root level:

tsx

import { QueryClient } from '@tanstack/react-query';

// Create the client instance
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 5, // 5 minutes
      retry: 1,
    },
  },
});

Note: For React Query v3, import from 'react-query' instead of '@tanstack/react-query'.

2Wrap your application with QueryClientProvider

Add the QueryClientProvider at the root of your application (typically in App.tsx, index.tsx, or _app.tsx for Next.js):

tsx

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      {/* Your app components go here */}
      <YourComponents />
    </QueryClientProvider>
  );
}

export default App;

For Next.js App Router with Server Components, create a providers component:

tsx

// app/providers.tsx
'use client';

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { useState } from 'react';

export function Providers({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(() => new QueryClient());

  return (
    <QueryClientProvider client={queryClient}>
      {children}
    </QueryClientProvider>
  );
}

Then wrap your layout:

tsx

// app/layout.tsx
import { Providers } from './providers';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

3Verify all React Query hooks are within the provider

Ensure that any component using React Query hooks is a child of QueryClientProvider:

tsx

// ✅ Correct - Component is wrapped by provider
function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <UserProfile /> {/* Can use hooks */}
    </QueryClientProvider>
  );
}

function UserProfile() {
  const { data } = useQuery({
    queryKey: ['user'],
    queryFn: fetchUser
  });
  // ...
}

// ❌ Wrong - Hook used outside provider
function App() {
  const { data } = useQuery({
    queryKey: ['user'],
    queryFn: fetchUser
  }); // Error!

  return (
    <QueryClientProvider client={queryClient}>
      <div>{data?.name}</div>
    </QueryClientProvider>
  );
}

4Check for version conflicts

If you're seeing this error despite having a provider, check for mixed imports between React Query versions:

bash

# Check installed versions
npm list react-query @tanstack/react-query

Ensure you're using consistent imports throughout your codebase:

tsx

// ✅ React Query v4+ (current)
import { useQuery } from '@tanstack/react-query';

// ❌ Don't mix with v3 imports
import { useQuery } from 'react-query';

If migrating from v3 to v4+, update all imports:

bash

# Remove old version
npm uninstall react-query

# Install new version
npm install @tanstack/react-query

Advanced notes

Singleton QueryClient Pattern: In most applications, you should create a single QueryClient instance and reuse it throughout your app. Avoid creating multiple instances unless you need isolated caching contexts.

Server-Side Rendering (SSR): When using SSR frameworks like Next.js, create the QueryClient instance inside a component (using useState) rather than at module scope to avoid sharing state between requests:

tsx

function Providers({ children }) {
  const [queryClient] = useState(() => new QueryClient());
  return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
}

Context Sharing in Micro-Frontends: If you're using multiple React Query instances across different bundles or micro-frontends, you may need to enable context sharing. However, the contextSharing prop is deprecated in v4+. Instead, ensure all parts of your application use the same React Query instance.

Testing: When testing components that use React Query hooks, wrap them in QueryClientProvider with a test client:

tsx

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { render } from '@testing-library/react';

const createTestQueryClient = () => new QueryClient({
  defaultOptions: { queries: { retry: false } },
});

test('my component', () => {
  const queryClient = createTestQueryClient();
  render(
    <QueryClientProvider client={queryClient}>
      <MyComponent />
    </QueryClientProvider>
  );
});

Custom Context: For advanced use cases where you need multiple isolated React Query contexts, you can create custom contexts:

tsx

import { QueryClient, QueryClientProvider, defaultContext } from '@tanstack/react-query';

const customContext = React.createContext<QueryClient | undefined>(undefined);

<QueryClientProvider client={queryClient} context={customContext}>
  {/* Components using this custom context */}
</QueryClientProvider>

Frequently asked questions

What does "No QueryClient set, use QueryClientProvider to set one" mean?: This error indicates that you're trying to use React Query hooks (like useQuery, useMutation, or useQueryClient) in a component that isn't wrapped by a QueryClientProvider. React Query relies on React's Context API to make the QueryClient instance accessible throughout your component tree. The QueryClient is the core instance that manages all queries, mutations, caching, and data synchronization in React Query.
How do I fix "No QueryClient set, use QueryClientProvider to set one"?: This error occurs when React Query hooks are used without wrapping the component tree in a QueryClientProvider. React Query requires a QueryClient instance to be provided via context to manage caching, queries, and mutations.
What causes "No QueryClient set, use QueryClientProvider to set one"?: QueryClientProvider is not wrapping the components that use React Query hooks QueryClientProvider is placed too low in the component tree (below components using hooks) Missing QueryClient instance creation before passing to QueryClientProvider
Is the "No QueryClient set, use QueryClientProvider to set one" error serious?: Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading

📚React Official Documentation