How to fix useQuery only works inside a component in React

ReactBEGINNERHIGH

This error occurs when React Query's useQuery hook is called outside the body of a function component or custom hook, violating React's Rules of Hooks. The hook must be called at the top level of a functional component, not inside callbacks, loops, or conditionals.

What this error means

This error indicates that you're attempting to use the useQuery hook from React Query (or similar query hooks from Apollo Client) in a location where React hooks are not allowed. React enforces strict rules about where hooks can be called - they must be invoked at the top level of function components or custom hooks, never inside regular functions, class components, event handlers, or effect callbacks. React hooks rely on a consistent calling order to maintain state between renders. When you call useQuery outside a component, React cannot track the hook's internal state or lifecycle, causing the hook system to fail. This is a fundamental restriction of React's hooks architecture, not specific to React Query. The error typically manifests as "Invalid hook call" or messages stating that hooks can only be called inside the body of a function component.

How to fix "useQuery only works inside a component"

1Verify your function is a proper React component

Ensure your function name starts with an uppercase letter and is used as a component:

javascript

// ✗ Wrong - lowercase function name
function myComponent() {
  const { data } = useQuery({ queryKey: ['data'], queryFn: fetchData });
  return <div>{data}</div>;
}

// ✓ Correct - uppercase component name
function MyComponent() {
  const { data } = useQuery({ queryKey: ['data'], queryFn: fetchData });
  return <div>{data}</div>;
}

React treats functions starting with uppercase letters as components, which allows hooks to work properly.

2Move useQuery to the top level of your component

Call useQuery at the top level of your function component, not inside callbacks or effects:

javascript

// ✗ Wrong - useQuery inside useEffect
function MyComponent() {
  const [data, setData] = useState(null);
  
  useEffect(() => {
    const { data } = useQuery({ queryKey: ['data'], queryFn: fetchData });
    setData(data);
  }, []);
  
  return <div>{data}</div>;
}

// ✓ Correct - useQuery at top level
function MyComponent() {
  const { data } = useQuery({ 
    queryKey: ['data'], 
    queryFn: fetchData 
  });
  
  return <div>{data}</div>;
}

React Query automatically handles refetching and caching - you don't need useEffect.

3Extract data fetching logic into a custom hook

If you need reusable query logic, create a custom hook (function starting with "use"):

javascript

// Custom hook - can use other hooks
function useProductData(productId) {
  return useQuery({
    queryKey: ['product', productId],
    queryFn: () => fetchProduct(productId),
    enabled: !!productId // Only run when productId exists
  });
}

// Use in component
function ProductDetails({ productId }) {
  const { data, isLoading, error } = useProductData(productId);
  
  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  
  return <div>{data.name}</div>;
}

Custom hooks can call other hooks and follow the same Rules of Hooks.

4For imperative fetching, use queryClient directly

If you need to fetch data imperatively (in event handlers or effects), use the queryClient methods instead of useQuery:

javascript

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

function MyComponent() {
  const queryClient = useQueryClient();
  
  const handleClick = async () => {
    // Use fetchQuery for imperative fetching
    const data = await queryClient.fetchQuery({
      queryKey: ['data'],
      queryFn: fetchData
    });
    console.log(data);
  };
  
  return <button onClick={handleClick}>Fetch Data</button>;
}

Alternatively, use the refetch function from useQuery:

javascript

function MyComponent() {
  const { data, refetch } = useQuery({
    queryKey: ['data'],
    queryFn: fetchData,
    enabled: false // Don't fetch on mount
  });
  
  const handleClick = () => {
    refetch(); // Trigger fetch imperatively
  };
  
  return <button onClick={handleClick}>Fetch Data</button>;
}

5Ensure QueryClientProvider is properly configured

Wrap your application with QueryClientProvider at the root level:

javascript

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

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <YourComponents />
    </QueryClientProvider>
  );
}

export default App;

For Next.js App Router, create a client component provider:

javascript

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

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

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

6Check for duplicate React installations

Verify you don't have multiple React versions causing hook conflicts:

bash

npm ls react
# or
yarn why react

If you see multiple versions, resolve them:

bash

# Remove node_modules and lock files
rm -rf node_modules package-lock.json
# or
rm -rf node_modules yarn.lock

# Reinstall dependencies
npm install
# or
yarn install

For monorepos or linked packages, use resolutions in package.json:

json

{
  "resolutions": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  }
}

How to fix useQuery only works inside a component in React

What this error means

Typical symptoms

Common causes

How to fix "useQuery only works inside a component"

Advanced notes

Related errors

Official resources & further reading