Troubleshooting

This guide covers common issues and their solutions.

Diagnostic Commands#

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#

Redis Connection Refused#

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#

Symptoms:

Error: NOAUTH Authentication required

Solutions:

  1. Verify password in MilliCache:

     1wp millicache config get storage.enc_password

  2. Re-set password:

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

  3. Test Redis password directly:

     1redis-cli -a "your-password" ping

Connection Timeout#

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#

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#

Pages Not Being Cached#

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

  1. 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

  2. Verify WP_CACHE:

     1wp config get WP_CACHE
 2# Should be: true

Cache Not Clearing#

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#

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#

advanced-cache.php Missing#

Symptoms:

wp millicache status
# advanced_cache: missing

Solution:

 1wp millicache drop

advanced-cache.php Outdated#

Symptoms:

wp millicache status
# advanced_cache: outdated

Solution:

 1wp millicache drop --force

Another Plugin's Drop-in#

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

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#

Slow Cache Hits#

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#

Symptoms:

  • Redis using too much memory
  • Keys being evicted

Diagnosis:

 1redis-cli info memory
 2wp millicache stats

Solutions:

  1. Increase Redis memory:

     1maxmemory 512mb

  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#

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#

Cache Not Isolated#

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#

Solutions:

  1. Run from network admin context:

     1wp millicache clear --network=1

  2. Check capabilities:

    • User needs manage_network

Debug Techniques#

Enable All Logging#

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

Check PHP Error Log#

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

Monitor Redis Commands#

 1redis-cli monitor

Test Request Flow#

 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#

 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#

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#