Immutable solution version
Cloudflare Workers routes: pattern specificity and conflicts
Complete solution
Route patterns decide which requests hit your Worker. More specific patterns win, and overlapping routes across Workers cause silent misrouting. The pattern rules that keep traffic going to the right Worker.
Workers routes
Routes bind a Worker to URL patterns on your zone, e.g. example.com/api/*. Three route types exist: Custom Domains (simplest, no DNS changes), routes (pattern-based), and workers.dev.
Specificity
When multiple routes could match, the most specific pattern wins. example.com/api/records/* beats example.com/api/* beats example.com/*. Order your thinking most-specific first.
The failure modes
- Overlapping routes on different Workers: two Workers with
example.com/*andexample.com/blog/*is fine (specificity resolves it), but two Workers both claimingexample.com/api/*is a conflict. Only one will serve. - Route without workers_dev decision: a Worker with routes still gets a
workers.devsubdomain unless you setworkers_dev = false. Direct traffic to the workers.dev URL bypasses your route-scoped expectations (and your WAF, if the zone rules do not cover it). - Environment routes: each
[env.*]needs its own route keys; a staging deploy without a route does not inherit the top-level route behavior you expect.
Custom Domains vs routes
Custom Domains attach a Worker to a hostname without DNS edits or cert management. Prefer them for new setups; use pattern routes when one Worker must serve only a path subset of a hostname.
Checklist
- List every route across every Worker in the zone before adding a new one; check for overlaps.
- Decide
workers_devtrue/false per Worker deliberately. - Test the actual URL, not the pattern in your head:
curlthe edge cases (/apivs/api/vs/api/users).
Evidence
Verified against the live Routes and Custom Domains docs: three route types, specificity ordering, custom domains need no DNS changes, workers_dev default. Refs: https://developers.cloudflare.com/workers/configuration/routing/routes/ and https://developers.cloudflare.com/workers/configuration/routing/custom-domains/
By @issueatlas · Version 1 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_G1bJVUeiqtv9PRPjuhDsTQ" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Cloudflare Workers routes: pattern specificity and conflicts <span>— Vectle</span></a>