Troubleshooting Breeze Cache: Common Issues and How to Fix Them

Breeze is a powerful caching plugin for WordPress, but like any complex software, users can occasionally run into issues. Based on community reports and common problems, this guide outlines some frequent challenges and their potential solutions.

1. Cache Not Respecting Expiry Time

The Problem: You've set a custom cache expiration time (e.g., 48 hours), but the cache seems to purge itself after the default 24 hours.

Why It Happens: This is often not a direct bug in Breeze. The cache can be cleared prematurely by other events on your site. A theme or another plugin might be updating content on a schedule, triggering a cache purge. Furthermore, Breeze has its own "Purge Cache After" setting; if this is not configured, it defaults to a 24-hour cycle.

How to Fix It:

• First, double-check the "Purge Cache After" setting in Breeze's advanced options to ensure it aligns with your desired expiration time.
• Investigate if you have any other plugins (e.g., a scheduled post updater, e-commerce stock manager, or SEO tool) that might be performing automatic updates and clearing the cache.
• Test by temporarily disabling other plugins to identify if there is a conflict.

2. "Never Cache URL" Feature Not Working

The Problem: You've added a URL pattern to the "Never Cache these URLs" field, but those pages are still being cached.

Why It Happens: This was a confirmed bug introduced in version 2.1.18 where the exclusion settings were not being properly saved to all necessary configuration arrays. The issue was specifically resolved in version 2.1.20.

How to Fix It:

• Update Breeze: Ensure you are running at least version 2.1.20 of the plugin. This is the most critical step.
• Verify the Pattern: Use a valid regex pattern. For a URL and all its subdirectories, a pattern like https://www.yourdomain.com/path/.* is typically effective.
• Check the Header: To confirm a page is not cached, open your browser's developer tools (Network tab), load the page, and check the HTTP headers of the HTML response. You should not see the X-Breeze-Cached: header.

3. The "Purge All Cache" Button is Broken

The Problem: Clicking the "Purge All Cache" button in the admin panel results in a 404 error, especially on installations where WordPress is in a subdirectory.

Why It Happens: A bug in the plugin can cause the AJAX call for the purge action to generate an incorrect URL, duplicating the subdirectory path and breaking the request. This can sometimes be accompanied by a fatal PHP error if certain classes cannot be found.

How to Fix It:

• This is typically an issue that requires a patch from the Breeze development team. Check your plugin version and update to the latest available release, as such bugs are usually fixed promptly.
• If the problem persists after an update, you may need to manually purge the cache via your hosting control panel's file manager by deleting the contents of the /wp-content/cache/breeze/ directory.

4. Cache Delivering Garbled/Gibberish Content

The Problem: Some external systems, like web crawlers or scripts using file_get_contents(), receive garbled, unreadable content instead of HTML.

Why It Happens: This is almost always caused by GZIP compression. Breeze serves compressed content to browsers that can handle it, but some scripts and tools do not automatically decompress it, resulting in the raw, compressed data being output.

How to Fix It:

• If you are building the crawling script, ensure it sends an Accept-Encoding HTTP header and can handle decompressing GZIP responses.
• If you need to serve uncompressed content to these tools, you can try disabling GZIP compression in Breeze's settings under the File Optimization tab. Be aware that this will disable compression for all visitors and may impact performance.

5. General Troubleshooting Steps

For any caching issue, always follow these basic steps first:

1. Clear All Caches: Purge the Breeze cache, your browser cache, and any additional server-level caches (like Varnish or OPcache) you may have.
2. Check for Conflicts: Temporarily switch to a default WordPress theme (like Twenty Twenty-Four) and disable all other plugins. If the problem resolves, reactivate them one-by-one to find the conflict.
3. Confirm User State: Always test while logged out of WordPress or using your browser's incognito/private mode. Caching is typically disabled for logged-in users.
4. Update Everything: Ensure WordPress, your theme, and all plugins (especially Breeze) are updated to their latest versions. Many bugs are patched in subsequent releases.

If you continue to experience issues after working through these steps, the WordPress.org support forums for the Breeze plugin are an excellent place to search for similar reports or ask for further community assistance.