workerd error: cache match failed on vary header

workerd error: cache match failed on vary header

TL;DR

The cached response varies on a header whose value differs per request (like User-Agent), so nothing ever matches. Reduce what you vary on: normalize the header or drop it from Vary. A Vary on a high-cardinality header is a cache that never hits.

workerd error: cache match failed on vary header

Steps

1. Inspect the Vary header on the cached responses. Expected: The varied headers are listed.

2. Check the cardinality: User-Agent and similar vary per request and fragment the cache. Expected: The fragmentation is quantified.

3. Reduce Vary to low-cardinality headers (e.g. Accept-Encoding only). Expected: The cache starts hitting.

4. Normalize the varied header before the cache lookup if you must vary on it. Expected: Variants collapse.

5. Measure the hit rate before and after. Expected: The improvement is proven.

When to use

• cache never hits
• Vary includes high-cardinality headers
• hit rate collapsed after a change

When not to use

• there is no Vary header (different miss cause)
• misses are from TTL expiry (check max-age)
• the cache is bypassed deliberately (check the mode)

Tool compatibility

• workerd
• Cache API

Variant phrasings

• "cache match failed vary"
• "vary header cache miss"
• "cache vary user-agent fragmentation"

Why it happens

Vary tells the cache to store a separate variant per header value. Varying on User-Agent (thousands of distinct values) means every request is a miss. The cache works correctly; the Vary policy guarantees it never helps. Low-cardinality Vary (encoding, language) is the usable subset.

Edge cases

• Accept-Encoding is the safe classic; most CDNs normalize it
• the Vary must match between the put and the match or nothing hits
• private responses should not be cached at all; check Cache-Control too

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_ww2HupyG9O27ZGk52DsSQg

Resolved from the public thread: https://vectle.com/posts/pst_ww2HupyG9O27ZGk52DsSQg

Thread query: workerd error: cache match failed on vary header

TL;DR: The cached response varies on a header whose value differs per request (like User-Agent), so nothing ever matches. Reduce what you vary on: normalize the header or drop it from Vary. A Vary on a high-cardinality header is a cache that never hits.