Troubleshooting

Queries Not Updating

Symptom: Query data doesn't update when expected.

Solutions:

Check query key stability:

// Bad: Creates new array each render
useQuery({ queryKey: [userId], queryFn });
 
// Good: Stable reference
const queryKey = useMemo(() => [userId], [userId]);
useQuery({ queryKey, queryFn });

Verify cache invalidation:

await client.invalidateQueries(['users']);

Check observer subscription:

const unsubscribe = client.subscribe(['users'], callback);
// Don't forget to unsubscribe

Memory Leaks

Symptom: Application memory grows over time.

Solutions:

Unsubscribe from queries:

useEffect(() => {
  const unsubscribe = client.subscribe(['users'], callback);
  return unsubscribe;
}, []);

Enable garbage collection:

const client = new QueryClient({
  defaultOptions: {
    gcTime: 5 * 60 * 1000, // 5 minutes
  },
});

Monitor observer count:

const stats = client.getCache().getStats();
console.log('Active entries:', stats.activeEntries);

Network Errors

Symptom: Fetch requests fail repeatedly.

Solutions:

Note that QueryClient does not apply a global retry option in the current release. For retrying mutations, use MutationEntry.mutateWithRetry():

const entry = client.getMutationCache().create({
  mutationId: 'mut-1',
  mutationFn: async (vars) => {
    const res = await fetch('/api/data', { method: 'POST', body: JSON.stringify(vars) });
    return res.json();
  },
});
 
// Retries up to 3 times with 1000ms delay
await entry.mutateWithRetry({ name: 'John' }, 3, 1000);

Implement error handling:

try {
  const data = await client.fetchQuery({
    queryKey: ['users'],
    queryFn: fetchUsers,
  });
} catch (error) {
  console.error('Fetch failed:', error);
}

Use error boundaries in React:

<ErrorBoundary fallback={<Error />}>
  <Users />
</ErrorBoundary>

Type Errors

Symptom: TypeScript compilation errors.

Solutions:

Ensure query keys are typed:

const queryKey = ['users'] as const;

Use generic types:

const data = await client.fetchQuery<User[]>({
  queryKey: ['users'],
  queryFn: fetchUsers,
});

Check import paths:

// Good
import { QueryClient } from '@soulcache/core';
import { useQuery } from '@soulcache/react';
 
// Bad: Don't import from internal paths

Performance Issues

Symptom: Application feels slow.

Solutions:

Reduce unnecessary fetches by invalidating the cache only when data changes:

await client.invalidateQueries(['users']); // marks entries stale
await client.fetchQuery({ queryKey: ['users'], queryFn }); // explicit refetch

Monitor metrics:

const metrics = client.getScheduler().getMetrics();
console.log('Tasks completed:', metrics.totalCompleted);

Troubleshooting

Troubleshooting

Queries Not Updating

Memory Leaks

Network Errors

Type Errors

Performance Issues

Related

On this page