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:

Check retry configuration:

// Configure retry globally on the client
const client = new QueryClient({
  defaultOptions: {
    retry: 3,
  },
});

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:

Increase stale time:

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

Use background refetching:

// staleTime is configured on the QueryClient, not per-query
const client = new QueryClient({
  defaultOptions: {
    staleTime: 5 * 60 * 1000, // Cache for 5 minutes
  },
});

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