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.

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.