Why this mode exists
Some hosts and CDNs return a saved page before WordPress loads. When PHP does not run, no WordPress plugin can inspect that original request. Cache Compatibility Mode embeds a small first-party script that asks WordPress to perform Bot Guard’s check after the page appears.
Behavior compared with Standard mode
| Area | Standard mode | Cache Compatibility Mode |
|---|---|---|
| Entry point | Before the page is rendered | Browser request after the cached page appears |
| Blocking | Immediate server-side response or redirect | Blocked overlay after the background result |
| JavaScript | Not required for core detection | Required |
| Strike data | Shared WordPress strike records and management controls | |
| Best use | Normal WordPress and cache stacks | Full-page caches that bypass WordPress entirely |
Requirements
- The Bot Guard cache script must be available.
- JavaScript must run in the visitor’s browser.
- The first-party background request must reach WordPress and must not be served from page cache.
- The site’s Content Security Policy must allow the plugin script and same-site request.
Enable and test
- Prove that cached visits are missing in Standard mode.
- Enable Cache Compatibility Mode and save.
- Clear the WordPress, host, CDN, and browser caches.
- Warm a normal HTML page, then visit it using a controlled suspicious browser identifier.
- Confirm one strike and one document entry in Activity Logs.
- Reach the limit and confirm the blocked overlay.
- Clear the strike and confirm the visitor regains access.
Limitations: A visitor who blocks JavaScript or the background request cannot be evaluated through this mode. Blocking may occur shortly after visible content appears. Most sites should use Standard mode.
Common failures
- No strike: verify the script loads, inspect the browser console, and confirm the background endpoint is excluded from caching/security rules.
- Two strikes: confirm Standard mode is not also initialized and that only document visits are submitted.
- Overlay does not clear: remove or expire the strike, verify whitelist status, and clear browser/page caches.