From 46767a7c325dbdfa706d5f16e5083f94d4329798 Mon Sep 17 00:00:00 2001 From: J Evans Date: Fri, 15 May 2026 14:59:38 -0700 Subject: [PATCH] [Workers Runtime] Document cache.put rejection of 301/302 redirects with query strings **Summary** Adds a note to the Workers Cache API docs explaining that cache.put() silently rejects 301/302 redirect responses when the cache key excludes the query string and the Location header contains it. This is an existing anti-cache-poisoning mitigation that is not currently documented, causing confusion for customers using the Cache API with redirect responses on custom domain Worker routes. --- src/content/docs/workers/runtime-apis/cache.mdx | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/src/content/docs/workers/runtime-apis/cache.mdx b/src/content/docs/workers/runtime-apis/cache.mdx index cc26647ff0a0df2..46b4fa7fb8b1e5b 100644 --- a/src/content/docs/workers/runtime-apis/cache.mdx +++ b/src/content/docs/workers/runtime-apis/cache.mdx @@ -130,6 +130,17 @@ The `stale-while-revalidate` and `stale-if-error` directives are not supported w `cache.put` returns a `413` error if `Cache-Control` instructs not to cache or if the response is too large. +:::note + +`cache.put` will silently reject a `301` or `302` redirect response if both of the following are true: + +1. The cache key does not include the query string (for example, a custom cache key set via Workers or Page Rules that strips the query string). +2. The `Location` header in the redirect response contains the request's query string. + +This is a cache-poisoning mitigation. To cache redirect responses with query strings, either include the query string in your cache key, or remove the query string from the `Location` header before calling `cache.put()`. This restriction does not apply on `.workers.dev` domains, which include the query string in the cache key by default. + +::: + ### `Match` ```js