ZiziCache Troubleshooting Guide and FAQ

This guide is based on the current plugin behavior and focuses on fixes that are actually supported by ZiziCache.

Quick Triage Checklist

• Confirm ZiziCache is active and you are testing from the WordPress root domain.
• Check that wp-content/cache is writable.
• Ensure cache lifespan is not set to never.
• Verify you are not using cache bypass parameters: ?nocache=1, ?bypass_optimization=1, ?zizi_bypass=1.
• If cache mode is set to LiteSpeed only on a non-LiteSpeed server, file caching is disabled by design.

Cache Not Working

Symptoms: no cached files, no cache hits, or no speed improvement.

• Cache lifespan: set a valid lifespan (not never).
• Logged-in users: if „cache logged-in users“ is disabled, admin sessions will bypass cache.
• Unknown query parameters: ZiziCache uses a whitelist. Unknown parameters disable caching. Add allowed parameters to the include list if needed.
• Page builders: editor query parameters (Elementor, Bricks, Divi, etc.) bypass cache. Test with a clean URL.
• LiteSpeed only mode: in this mode no .html.gz files are written; cache lives in LiteSpeed server cache only.

Content Not Updating

Symptoms: old content still visible after updates.

• Run a full purge: wp zizi-cache purge-pages or wp zizi-cache purge-everything.
• Use the admin UI purge if you prefer a GUI.
• If using LiteSpeed-only mode, purge must happen at the server layer (ZiziCache triggers this internally, but file cache wont exist).

Preload Issues

Symptoms: preload stalls or only partially warms the cache.

• Preload uses a queue file: wp-content/cache/zizi-cache/preloader-list.txt. If stuck, delete the file and run wp zizi-cache preload-cache again.
• Preload runs in batches and relies on WP-Cron for continuation. Make sure WP-Cron is working.
• Separate mobile cache doubles work. Disable it temporarily to reduce load.

Object Cache (Redis / Memcached) Issues

• Only one object cache backend can be active. Enabling Memcached disables Redis and vice versa.
• The drop-in file must exist: wp-content/object-cache.php.
• Memcached requires a PHP extension (memcache or memcached). If missing, the drop-in falls back to the native WP object cache.
• Flush object cache via: wp zizi-cache object-cache-flush (backend-agnostic).

OPcache Issues

• Flush via CLI: wp zizi-cache opcache flush or wp zizi-cache opcache-flush.
• Flush can fail if the Zend OPcache extension is not loaded.
• Flush can be blocked by opcache.restrict_api if the server address is not allowed.

Quicklink / Speculative Loading Conflicts

• Quicklink and Speculation Rules can both be enabled. If they use the same mode or page types, you may see duplicate prefetching.
• Check the current state via: wp zizi-cache quicklink-status.

Logs and Diagnostics

• Main log file: wp-content/plugins/zizi-cache/zizi-log.log.
• Logs are throttled to prevent spam and rotate automatically (5 files, 5 MB each).
• REST diagnostics (admin-only):
  • /wp-json/zizi-cache/v1/server-info
  • /wp-json/zizi-cache/v1/performance-metrics
  • /wp-json/zizi-cache/v1/cache-stats
  • /wp-json/zizi-cache/v1/uncached-urls

FAQ

• Why are there no cache files?
  In LiteSpeed-only mode, file cache is skipped by design.
• Does CLI support per-URL purge?
  No. CLI purges are global. Per-URL purge is available via REST in the admin UI.
• Can I enable both Redis and Memcached?
  No. The plugin enforces mutual exclusivity.