Troubleshooting Guide

Quick solutions for common problems.

Decision Tree

Quick Links

Issue Type	Go to
Cache not working	Cache Issues
Locks not working	Lock Issues
Slow performance	Performance Issues
Need to debug	Debugging

Common Quick Fixes

"Cache not invalidating"

// Check tag names match
@Cached({ tags: ['users'] })  // Producer
await cache.invalidateTags(['users']);  // Consumer - same tag!

"Lock timeout"

// Increase timeout
@WithLock({
  key: 'mykey',
  waitTimeout: 10000,  // Increase from default
})

"Connection refused"

# Check Redis is running
redis-cli ping

# Check host/port
echo $REDIS_HOST $REDIS_PORT

"High latency"

# Check Redis latency
redis-cli --latency

# Check slow log
redis-cli SLOWLOG GET 10

Getting Help

1. Check this troubleshooting guide
2. Search GitHub Issues
3. Ask in Discord
4. Open a new issue with reproduction

Next Steps

• Cache Issues — Detailed cache troubleshooting
• Lock Issues — Lock and contention issues
• Performance Issues — Latency and throughput
• Debugging — Tools and techniques