Cache Exclusions

Cache Exclusions

Everything that keeps a page out of the cache, and how to add your own. Configured under Exceptions.

The four mechanisms

Mechanism	Matching	Use for
Bypass paths	Segment boundaries	Whole sections — /account/, /checkout/
Bypass cookies	Prefix on the cookie name	Any visitor with state
Bypass query params	Exact parameter name	Actions — add-to-cart
Ignored query params	Exact parameter name	Tracking noise you want stripped, page still cached

Path matching

Matching is on segment boundaries, so /checkout/ protects /checkout, /checkout/, and everything below it — but not /checkout-summary. That distinction is the reason a naive prefix match is wrong: /cart should not accidentally bypass /cartography.

A bypass path of / protects the site root only, not the whole site.

The unknown_query rule

Any query parameter that is not on the ignored list causes a bypass. This is the behaviour that surprises people most, and it is deliberate.

• It means nobody can fill your disk by requesting ?a=1, ?a=2, ?a=3.
• It means a parameter your site genuinely uses can never be silently dropped into a wrong cache hit.

The cost is that a legitimate parameter you forgot to declare bypasses instead of caching. That is the right direction to fail in.

To cache across a parameter, add it to ignored query parameters — the page is cached once and the parameter is stripped from the key. To force a bypass, add it to bypass query parameters.

Cookies

Prefix match, so wordpress_logged_in_ covers every hashed variant. This is why a signed-in administrator never sees a cache hit and why testing must be done logged out.

Per-response exclusion from code

// Anywhere before the response is captured
if ( my_page_is_personalised() ) {
    define( 'DONOTCACHEPAGE', true );
}

Adding to the compiled policy

gt_performance_cache_policy is the right hook when you want the origin and the edge to agree:

add_filter( 'gt_performance_cache_policy', function ( array $policy ) {
    $policy['bypass_paths'][]   = '/members/';
    $policy['bypass_cookies'][] = 'my_session_';
    return $policy;
} );

Because the Cloudflare rule is compiled from this same policy, one addition protects both layers. Adding a path only in the Cloudflare dashboard leaves your origin caching it.

What is excluded automatically

• Everything the active commerce adapters declare. See Commerce Safety.
• Feeds and robots requests.
• Admin, AJAX and cron requests.
• Any response that sets a cookie, is not HTTP 200, is not text/html, or carries no-store or private.

Checking your work

wp gt-performance cache explain --page-url=https://example.com/members/

names the deciding rule. Turn on Debug mode to get X-GT-Cache-Reason in the response headers while you test.

Related

Page Cache · Commerce Safety · Diagnostics