Cache Troubleshooting Guide
Overview
This guide helps you troubleshoot common cache issues, including cache not working, high memory usage, stale data, and backend-specific problems.
Common Issues
Cache Not Working
Symptoms: - Cache statistics show 0 hits - All calls are cache misses - No performance improvement
Diagnosis:
from app.api.system import get_cache_statistics
stats = await get_cache_statistics()
print(f"Cache enabled: {stats['enabled']}")
print(f"Backend: {stats['backend']}")
print(f"Hit rate: {stats['statistics']['hit_rate']:.2%}")
Solutions:
-
Check if caching is enabled:
-
Verify backend is initialized:
-
Check logs for cache errors:
-
Verify cache directory is writable (file backend):
High Memory Usage
Symptoms: - Memory usage is high - Cache size is large - System performance degradation
Diagnosis:
from app.core.cache.manager import get_cache_manager
manager = await get_cache_manager()
backend = await manager._get_backend()
if hasattr(backend, "async_size"):
size = await backend.async_size()
print(f"Cache size: {size} entries")
Solutions:
-
Reduce cache size:
-
Reduce TTL values:
-
Switch to Redis or file backend:
-
Clear cache periodically:
Stale Data
Symptoms: - Cached data is outdated - Changes not reflected immediately - Data doesn't match Home Assistant
Diagnosis:
# Check TTL values
from app.core.cache.config import get_cache_config
config = get_cache_config()
print(config.get_all_config())
Solutions:
-
Reduce TTL values:
-
Verify cache invalidation is working:
-
Clear cache manually:
-
Check invalidation patterns:
Low Hit Rate
Symptoms: - Hit rate <50% - Cache not effective - High number of cache misses
Diagnosis:
from app.api.system import get_cache_statistics
stats = await get_cache_statistics()
print(f"Hit rate: {stats['statistics']['hit_rate']:.2%}")
print(f"Per-endpoint stats: {stats['per_endpoint']}")
Solutions:
-
Increase TTL values:
-
Check for parameter variations:
-
Review cache invalidation patterns:
-
Optimize cache keys:
Backend-Specific Issues
Redis Connection Problems
Symptoms: - Redis backend not working - Connection errors in logs - Fallback to memory backend
Diagnosis:
from app.core.cache.manager import get_cache_manager
manager = await get_cache_manager()
backend = await manager._get_backend()
print(f"Backend: {backend.__class__.__name__}")
# Should be RedisCacheBackend, not MemoryCacheBackend
Solutions:
-
Check Redis URL:
-
Verify Redis is running:
-
Check Redis connection:
-
Check Redis authentication:
-
Check network connectivity:
File Backend Issues
Symptoms: - File backend not working - Permission errors in logs - Fallback to memory backend
Diagnosis:
from app.core.cache.manager import get_cache_manager
manager = await get_cache_manager()
backend = await manager._get_backend()
print(f"Backend: {backend.__class__.__name__}")
# Should be FileCacheBackend, not MemoryCacheBackend
Solutions:
-
Check cache directory permissions:
-
Create cache directory:
-
Check disk space:
-
Verify aiofiles is installed:
-
Check file system permissions:
Memory Backend Issues
Symptoms: - High memory usage - Cache size exceeds limit - Performance degradation
Solutions:
-
Reduce cache size:
-
Clear cache periodically:
-
Switch to Redis or file backend:
Debugging Tips
Enable Debug Logging
Check Cache Statistics
Inspect Cache Keys
from app.core.cache.manager import get_cache_manager
manager = await get_cache_manager()
keys = await manager.keys("entities:*")
print(f"Entity cache keys: {keys}")
Test Cache Operations
from app.core.cache.manager import get_cache_manager
manager = await get_cache_manager()
# Test set
await manager.set("test_key", "test_value", ttl=60)
# Test get
value = await manager.get("test_key")
print(f"Value: {value}")
# Test delete
await manager.delete("test_key")
Getting Help
If you're still experiencing issues:
- Check logs: Look for cache-related errors
- Review documentation: See Architecture and Configuration
- Check statistics: Use
get_cache_statistics()to diagnose issues - Test cache operations: Verify cache is working with test operations
- Report issues: Create a GitHub issue with logs and statistics