Question 3 of 6
Workers not applied
Customer ticket
Subject: Workers not applied
I've just added a Worker on the Cloudflare Dashboard for my website: it works in the debugger but doesn't work when I query the site. Why is that? Is there anything to activate or anything I could check?
1. Email reply to the customer
Hi there,
Thanks for reaching out, and congratulations on your first Worker! What you’re seeing is very common. When the Worker runs correctly in the dashboard preview, your code is fine. What’s missing is the link between the Worker and your website’s traffic. The preview runs your code directly, but real requests to example.com only reach the Worker when a route or custom domain tells Cloudflare to send them there. Here’s what to check, roughly in order of how often it’s the cause:
1. The latest version is deployed, not just saved or previewed
In the dashboard editor, make sure you clicked Deploy. Under Workers & Pages > your Worker > Deployments, the version you tested should be the active one, at 100% of traffic.
2. A route (or custom domain) is attached to the Worker
New Workers are only reachable on their *.workers.dev address by default. To run the Worker on your site, go to Workers & Pages > your Worker > Settings > Domains & Routes > Add > Route, choose the zone example.com and enter a pattern. For most sites that will be:
example.com/*
www.example.com/*Use a Custom Domain instead only if the Worker is the whole application (with no origin server behind it).
3. The route pattern really matches the URL you’re testing
example.com/*does not matchwww.example.com. Add a second route, or use*.example.com/*for subdomains. (Be aware that*example.com/*also matches other hostnames ending in “example.com”.)- A pattern without a trailing
*(e.g.example.com/) matches only that exact path. It won’t match/aboutor URLs with a query string. - The path part is case-sensitive, and a scheme prefix (
https://) limits the route to that scheme. - A more specific route that has no Worker assigned overrides broader patterns, so check for leftover routes like that.
4. The hostname has a proxied DNS record
Workers routes only run on traffic that passes through Cloudflare’s proxy. In DNS > Records, the record for that hostname must exist and be Proxied (orange cloud). A grey-clouded (DNS-only) record sends visitors straight to your server and skips the Worker entirely.
5. Free plan request limit and “fail open”
On the Workers Free plan there is a limit of 100,000 requests per day. If a route is set to fail open and the limit is reached, requests simply skip the Worker until the counter resets at midnight UTC, which looks exactly like “the Worker isn’t applied”.
6. Rule out browser caching
The Worker runs in front of Cloudflare’s cache, but your browser may still be showing an old copy. Test with curl or a private window:
curl -svo /dev/null https://example.com/some/path
# Look for a header your Worker sets, or a change in behaviour.
# To watch live requests reaching the Worker:
npx wrangler tail <your-worker-name>If wrangler tail (or Logs > Live in the dashboard) shows nothing when you load the page, the request isn’t being routed to the Worker, so recheck steps 2 to 4. If you see requests but with exceptions, send me the log output and I’ll help with the code.
If none of this solves it, reply with the Worker name, the route(s) you configured and the exact URL you’re testing, and I’ll look at it straight away.
Kind regards,
Marwan
Cloudflare Customer Support
2. Thought process
“Works in the preview but not on the site” almost always means the code is fine and the routing isn’t. The dashboard preview (Quick Editor, which uses wrangler dev --remote behind the scenes) runs the script directly, without route matching or DNS. So I focused on the path a real request takes:
- DNS: is the record present and proxied, so the request reaches Cloudflare at all?
- Zone: is the route defined on the zone that actually serves the hostname?
- Route: does the pattern match host, path and scheme, and is there a more specific route with no Worker?
- Deployment: is the version that was tested actually deployed?
- Limits: a Free plan Worker that fails open once over quota looks like “not applied”.
- Client: browser caching hides changes. Workers run before the CDN cache, so edge cache isn’t the cause.
Since I have access to their settings, in practice I would check the route list and DNS proxy status first, then tell them exactly which item was wrong. I wrote the email as a checklist so the customer can verify it themselves and learn the routing model. I also gave them wrangler tail so they can see for themselves whether requests reach the Worker, which separates routing problems from code problems.
3. Tools I would use, and why
| Tool | Why |
|---|---|
Dashboard: Workers & Pages > Settings > Domains & Routes | Confirm a route or custom domain exists, is on the right zone and has the right pattern. |
Dashboard: Deployments / Versions | Check that the tested version is deployed and receiving 100% of traffic. |
Dashboard: DNS > Records | Confirm the hostname has a proxied (orange-cloud) record, which routes require. |
npx wrangler tail / Workers Logs (Live) | Live view of invocations. No events at all means the request isn’t routed; exceptions point to a code problem. |
curl -svo /dev/null https://example.com/path | Repeatable test that bypasses browser cache and shows any headers the Worker sets. |
Workers Metrics (requests, errors, invocation statuses) | Shows whether the Worker gets traffic, and spots Free plan limit or exceeded-CPU problems. |
wrangler.jsonc / wrangler.toml review | If deployed with Wrangler, check that routes and zone_name are set and weren’t overwritten by a later deploy. |