workerd error: cache match failed on vary header

Not specified by the original author.

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.

Not specified by the original author.

TL;DR

The Cache API only stores GET responses. Calling cache.put with a POST, PUT, or any non-GET request throws. Cache only idempotent GETs; for other methods, cache the derived GET-equivalent or skip caching and note why.

The query

workerd error: cache.put failed, request method must be GET

Use this when

• cache.put(request, response) throws naming the method.
• You tried to cache POST API responses or form submissions.
• The code caches 'every request' without checking the method.

Not for

• 'cache API put failed, cache unavailable in workerd' (availability problem).
• Stale or wrong cached content (invalidation logic bug).
• Cache match misses (key problem).

Steps

Step 1: Guard the put by method

if (request.method === "GET") {
  const cache = caches.default;
  await cache.put(request, response.clone());
}

Expected result: non-GET requests skip caching instead of throwing. The error disappears.

Step 2: Decide what POST caching should mean

If the intent was caching expensive POST results, derive a cache key from the method plus a hash of the body, and store under a synthetic GET request.

const key [your value] Request("YOUR_HOST/post/" + bodyHash, { method: "GET" });
await cache.put(key, response.clone());

Expected result: POST results are cached under a GET-shaped key you control. Lookups use the same derivation.

Step 3: Clone before putting

cache.put consumes the response body. Always clone for the cache copy and return the original.

Expected result: the client still receives the body. Forgetting the clone breaks the response AND the cache write.

Step 4: Verify with a POST and a GET

Expected result: POSTs no longer throw; GETs cache and hit as before.

Step 5: Document the caching contract

Expected result: the codebase records which methods are cached and how POST-shaped work is keyed, so the next person does not reintroduce the unguarded put.

Why it happens

HTTP caching semantics are defined around GET. The Cache API enforces this at the storage layer rather than silently storing something that intermediaries would never serve. Code that treats 'request' as generic trips the guard the first time a non-GET flows through.

Edge cases

• Guard HEAD explicitly too and test it; do not assume it behaves like GET.
• cache.put with a string URL key is allowed; the method restriction applies to Request keys.
• Only the default cache and named caches share this rule; there is no opt-out.
• Method-specific responses still need correct cache keys even for GETs; vary headers matter.

Provenance

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

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

Thread query: workerd error: cache.put failed, request method must be GET

TL;DR: The Cache API only stores GET responses. Calling cache.put with a POST, PUT, or any non-GET request throws. Cache only idempotent GETs; for other methods, cache the derived GET-equivalent or skip caching and note why.

Not specified by the original author.

TL;DR

When workerd throws "invalid redirect value" and your own code looks correct, the next step is checking whether it is a known upstream bug. Search the cloudflare/workerd GitHub issues for that exact string, open the matching issue, and read the repro, the maintainer response, and any linked fix. Most of the time you will find either a confirmed bug with a workaround or a "working as intended" reply that points at the real mistake in your redirect.

site:github.com/cloudflare/workerd "invalid redirect value"

Steps

1. Search the workerd issue tracker for the exact error string:

gh issue list --repo cloudflare/workerd --search "invalid redirect value" --limit 20

Expected: a short list of issues whose titles or bodies contain the string. If the gh CLI is not set up, the same search works in the GitHub web UI on the cloudflare/workerd repo.

2. Open the top matches and compare the stack trace and repro to yours. Look for the maintainer's label: confirmed bug, duplicate of another issue, or closed as expected behavior.

Expected: you can tell within a few minutes whether your case matches a known report or is new.

3. If it matches a known issue, check for linked pull requests and the release they landed in, then check your wrangler's workerd version against that release.

Expected: either a fix version you can upgrade to, or a posted workaround you can apply now.

4. If nothing matches, file a new issue with a minimal repro: the smallest worker that throws, the workerd version from wrangler --version, and the full stack.

Expected: the report is actionable for maintainers instead of another vague "redirect broken" post.

Use this when

• Workerd throws "invalid redirect value" and your redirect code looks right
• You want to know if the error is a known workerd bug before rewriting your code
• You need the upstream workaround or the fix version

Not for this skill when

• The redirect target is a relative URL you control; fix it with an absolute URL instead (see the Response.redirect skill)
• The error comes from your own framework's redirect helper, not workerd
• You already found the matching issue and just need the fix

Variant phrasings

• cloudflare workerd invalid redirect value github issue
• workerd Response redirect throws invalid redirect value bug
• "invalid redirect value" cloudflare workers issue tracker

Why it happens

The "invalid redirect value" error sits exactly on the boundary between user error (relative or malformed redirect targets) and runtime strictness (workerd enforcing the spec harder than browsers do). That boundary is where upstream bugs live, so the issue tracker is often the fastest route to an answer.

Edge cases

• An issue closed as "working as intended" usually means the reporter passed a relative URL; re-check your redirect target before assuming a bug.
• Duplicate issues get closed fast; search before filing so your report lands on the live thread.
• The fix version in a merged PR may not be in the wrangler release you have; check the changelog rather than assuming.
• Workerd behavior can differ between local dev and deployed; note which one your repro uses when comparing with an issue.

Provenance

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

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

Thread query: site:github.com/cloudflare/workerd "invalid redirect value"

TL;DR: When workerd throws "invalid redirect value" and your own code looks correct, the next step is checking whether it is a known upstream bug. Search the cloudflare/workerd GitHub issues for that exact string, open the matching issue, and read the repro, the maintainer response, and any linked fix. Most of the time you will find either a confirmed bug with a workaround or a "working as intended" reply that points at the real mistake in your redirect.