Troubleshooting

This guide covers common issues and their solutions.

Diagnostic Commands#Copied!

Start troubleshooting with these commands:

 1# Check overall status
 2wp millicache status
 3
 4# Test Redis connection
 5wp millicache test
 6
 7# View cache statistics
 8wp millicache stats
 9
10# Check configuration sources
11wp millicache config get --show-source

Connection Issues#Copied!

Redis Connection Refused#Copied!

Symptoms:

Error: Connection refused [tcp://127.0.0.1:6379]

Solutions:

1. Check Redis is running:

    1redis-cli ping
    2# Should return: PONG
    3
    4# Or check service status
    5sudo systemctl status redis
   

2. Verify Redis is listening:

    1netstat -tlnp | grep 6379
    2# or
    3ss -tlnp | grep 6379
   

3. Check firewall rules:

    1sudo ufw status
    2# Allow if needed
    3sudo ufw allow 6379/tcp
   

4. Verify configuration:

    1wp millicache config get storage
   

Authentication Failed#Copied!

Symptoms:

Error: NOAUTH Authentication required

Solutions:

1. Verify credentials in MilliCache:

    1wp millicache config get storage.username
    2wp millicache config get storage.enc_password
   

2. Re-set credentials:

    1wp millicache config set storage.username "your-username"
    2wp millicache config set storage.enc_password "your-password"
   

3. Test Redis credentials directly:

    1# With a named user (Redis ACL)
    2redis-cli -u "redis://your-username:your-password@127.0.0.1:6379" ping
    3
    4# With the default user (password only)
    5redis-cli -a "your-password" ping
   

Connection Timeout#Copied!

Symptoms:

Error: Connection timed out

Solutions:

1. Check network connectivity:

    1telnet redis-host 6379
   

2. Verify DNS resolution:

    1host redis-host
   

3. Check for network issues:

    1ping redis-host
    2traceroute redis-host
   

4. Increase PHP timeout (temporary):

    1ini_set('default_socket_timeout', 10);
   

Unix Socket Permission Denied#Copied!

Symptoms:

Error: Permission denied [unix:///var/run/redis/redis.sock]

Solutions:

1. Check socket exists:

    1ls -la /var/run/redis/redis.sock
   

2. Add web server user to redis group:

    1sudo usermod -aG redis www-data
    2sudo systemctl restart php-fpm
   

3. Check Redis socket permissions:

    1# /etc/redis/redis.conf
    2unixsocketperm 770
   

---

Caching Issues#Copied!

Pages Not Being Cached#Copied!

Symptoms:

• X-MilliCache-Status: bypass
• Cache entries count stays at 0
• Pages always show "miss"

Diagnosis:

1. Enable debug mode:

    1define( 'MC_CACHE_DEBUG', true );
   

2. Check debug headers:

    1curl -I https://example.com/
    2# Look for X-MilliCache-* headers
   

   Tip: The MilliCache Browser Extension adds a dedicated panel to your browser's developer tools for easier debugging.

Common causes:

Header Status	Cause	Solution
No headers	Drop-in not installed	wp millicache drop
bypass	Rule triggered	Check below
miss	First request	Normal, will cache

3. Check for bypass reasons:

   • Logged in? Log out and test
   • POST request? Only GET/HEAD cached
   • Excluded cookie? Check MC_CACHE_NOCACHE_COOKIES
   • Excluded path? Check MC_CACHE_NOCACHE_PATHS
   • TTL = 0? Check MC_CACHE_TTL
   • Oversized response? Responses larger than 5MB (before compression) are never stored

4. Verify WP_CACHE:

    1wp config get WP_CACHE
    2# Should be: true
   

Cache Not Clearing#Copied!

Symptoms:

• Old content still showing
• Updates not reflected

Solutions:

1. Force clear all cache:

    1wp millicache clear
   

2. Clear Redis directly:

    1redis-cli FLUSHDB
   

3. Check for external cache (CDN, Varnish):

   • Clear CDN cache separately
   • Check for upstream caching

4. Verify clearing hooks working:

    1add_action( 'millicache_cache_cleared', function() {
    2    error_log( 'Cache cleared successfully' );
    3} );
   

Stale Content After Updates#Copied!

Symptoms:

• Updated content shows old version
• Takes time to refresh

Diagnosis:

1. Check grace period behavior:

   • Is content within grace period?
   • Grace serves stale during regen

2. Verify post update triggers clearing:

    1add_action( 'millicache_cache_cleared_by_posts', function( $ids ) {
    2    error_log( 'Cleared posts: ' . implode( ', ', $ids ) );
    3} );
   

Solutions:

1. Clear specific post:

    1wp millicache clear --id=123
   

2. Delete instead of expire:

    1wp millicache clear --id=123
    2# Without --expire flag = immediate delete
   

---

Drop-in Issues#Copied!

advanced-cache.php Missing#Copied!

Symptoms:

wp millicache status
# advanced_cache: missing

Solution:

 1wp millicache drop

advanced-cache.php Outdated#Copied!

Symptoms:

wp millicache status
# advanced_cache: outdated

Solution:

 1wp millicache drop --force

Another Plugin's Drop-in#Copied!

Symptoms:

Warning: Existing advanced-cache.php from another plugin detected.

Solution:

1. Deactivate other caching plugins
2. Delete old drop-in:

    1rm wp-content/advanced-cache.php
   

3. Install MilliCache drop-in:

    1wp millicache drop
   

Symlink Not Working#Copied!

Symptoms:

Notice: Symlinks not supported, using file copy.

Cause: File system or hosting doesn't support symlinks

Impact: None—file copy works identically

If you want symlinks:

1. Check file system supports symlinks
2. Verify permissions on wp-content/
3. Some hosts disable symlinks for security

---

Performance Issues#Copied!

Slow Cache Hits#Copied!

Symptoms:

• Cache hits taking >50ms
• Expected: 5-15ms

Diagnosis:

1. Check network latency:

    1redis-cli --latency
   

2. Check Redis performance:

    1redis-cli info stats | grep instantaneous_ops_per_sec
   

Solutions:

1. Use Unix sockets:

    1define( 'MC_STORAGE_HOST', '/var/run/redis/redis.sock' );
   

2. Enable persistent connections:

    1define( 'MC_STORAGE_PERSISTENT', true );
   

3. Run Redis locally instead of remote

High Memory Usage#Copied!

Symptoms:

• Redis using too much memory
• Keys being evicted

Diagnosis:

 1redis-cli info memory
 2wp millicache stats

Solutions:

1. Increase Redis memory (live, no restart):

    1redis-cli CONFIG SET maxmemory 512mb
   

   Or run the same command against the configured server via wp millicache cli. CONFIG SET is lost on restart, so add maxmemory 512mb to your Redis config file (or run redis-cli CONFIG REWRITE) to keep it.

2. Reduce TTL:

    1define( 'MC_CACHE_TTL', 3600 );  // 1 hour
   

3. Enable compression:

    1define( 'MC_CACHE_GZIP', true );
   

4. Reduce cache variations:

   • Review MC_CACHE_UNIQUE settings
   • Add more items to ignore lists

Cache Fragmentation#Copied!

Symptoms:

• High used_memory_rss vs used_memory ratio
• Slow Redis operations

Diagnosis:

 1redis-cli info memory | grep fragmentation

Solutions:

1. Restart Redis (clears fragmentation)
2. Use jemalloc (better memory allocator)
3. Schedule periodic restarts (for high-write workloads)

---

Multisite Issues#Copied!

Cache Not Isolated#Copied!

Symptoms:

• Site A content appears on Site B
• Clearing Site A affects Site B

Diagnosis:

 1wp millicache stats --flag="*" --format=json
 2# Check flag prefixes

Solutions:

1. Verify network activation:

   • Plugin must be network-activated
   • Not per-site activated

2. Check flag prefixes:

    1wp millicache stats --flag="1:*"  # Site 1
    2wp millicache stats --flag="2:*"  # Site 2
   

Network Clear Not Working#Copied!

Solutions:

1. Run from network admin context:

    1wp millicache clear --network=1
   

2. Check capabilities:

   • User needs manage_network

---

Debug Techniques#Copied!

Enable All Logging#Copied!

 1// wp-config.php
 2define( 'WP_DEBUG', true );
 3define( 'WP_DEBUG_LOG', true );
 4define( 'MC_CACHE_DEBUG', true );

Check PHP Error Log#Copied!

 1tail -f /var/log/php/error.log

Monitor Redis Commands#Copied!

 1redis-cli monitor

Test Request Flow#Copied!

 1# With headers
 2curl -v https://example.com/ 2>&1 | grep -i millicache
 3
 4# Multiple requests to test caching
 5for i in {1..3}; do
 6  curl -s -o /dev/null -w "Request $i: %{http_code} in %{time_total}sn" https://example.com/
 7done

Check Cache Entry#Copied!

 1# Open Redis CLI
 2wp millicache cli
 3
 4# Find cache keys
 5KEYS mll:*
 6
 7# Get specific entry
 8GET mll:cache:abc123

Getting Help#Copied!

If issues persist:

1. Gather diagnostics:

    1wp millicache status --format=json > status.json
    2wp millicache config get --format=json > config.json
    3wp millicache stats --format=json > stats.json
   

2. Check PHP/WordPress versions

3. Report issues: GitHub Issues

Next Steps#Copied!

• FAQ - Common questions
• Storage Backends - Configuration and optimization
• WP-CLI Commands - Command reference