From 3b2264ad6b1e3f65ac374d797676f86e3179be92 Mon Sep 17 00:00:00 2001
From: George Oastler <goastler4@gmail.com>
Date: Fri, 16 Oct 2026 01:26:46 +0100
Subject: [PATCH] docs: warn not to enable Workers Cache on the Protect worker

With Workers Cache on, Cloudflare serves cached responses before the
worker runs, so those requests never reach Protect.
---
 src/content/docs/en/protect-edge/cloudflare-worker.mdx | 4 ++++
 src/content/docs/en/protect-edge/troubleshooting.mdx   | 8 ++++++++
 2 files changed, 12 insertions(+)

diff --git a/src/content/docs/en/protect-edge/cloudflare-worker.mdx b/src/content/docs/en/protect-edge/cloudflare-worker.mdx
index 4b060850292a2..5364090205136 100644
--- a/src/content/docs/en/protect-edge/cloudflare-worker.mdx
+++ b/src/content/docs/en/protect-edge/cloudflare-worker.mdx
@@ -150,6 +150,10 @@ Then `wrangler deploy`. The worker now runs on every request to `www.<your-domai
 
 **Deploy on a route, not `workers.dev`, before testing.** A `workers.dev` URL is not in front of anything, so there is no origin for `fetch(request)` to reach: an allowed request re-enters the worker and Cloudflare returns **Error 1042**. That is expected on `workers.dev` and not a fault in your config. Only a route has an origin behind it.
 
+:::caution[Do not enable Workers Cache]
+Leave the `[cache]` section out of `wrangler.toml`. With `[cache] enabled = true`, Cloudflare checks its cache before running the worker, so a cached response is served without Protect checking the request. By default one cached copy is served to every visitor, which means a page cached after one visitor was allowed is then served to bots too. See [Cloudflare's Workers Cache docs](https://developers.cloudflare.com/workers/cache/).
+:::
+
 Your account manager notifies you when a new `worker.js` is available. Replace the file and re-run `wrangler deploy`. Secrets persist.
 
 ### 1e. Verify the worker
diff --git a/src/content/docs/en/protect-edge/troubleshooting.mdx b/src/content/docs/en/protect-edge/troubleshooting.mdx
index f26dd66ba9b19..4d27f5bf10a65 100644
--- a/src/content/docs/en/protect-edge/troubleshooting.mdx
+++ b/src/content/docs/en/protect-edge/troubleshooting.mdx
@@ -97,6 +97,14 @@ Common block sources:
 
 Check the dashboard's traffic summary for your site to see request throughput broken down by verdict.
 
+## Some requests skip Protect entirely
+
+**Symptom:** Pages load for visitors who should be blocked or challenged, and those requests are missing from the dashboard's traffic summary.
+
+**Cause:** Workers Cache is enabled in `wrangler.toml` (`[cache] enabled = true`). Cloudflare then serves cached responses before the worker runs, so Protect never sees those requests. See [Cloudflare's Workers Cache docs](https://developers.cloudflare.com/workers/cache/).
+
+**Fix:** Remove the `[cache]` section from `wrangler.toml` and run `wrangler deploy`.
+
 ## Configuration drift
 
 **Symptom:** Behaviour changed without anyone deploying. Verify commands that previously worked now fail (or vice versa).