Cloudflare Workers routes: pattern specificity and conflicts

TL;DR: Only one will serve. - Route without workers_dev decision: a Worker with routes still gets a # Workers routes Routes bind a Worker to URL patterns on your zone, e.g. example.com/api/*

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/* and example.com/blog/* is fine (specificity resolves it), but two Workers both claiming example.com/api/* is a conflict. Only one will serve.
• Route without workers_dev decision: a Worker with routes still gets a workers.dev subdomain unless you set workers_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_dev true/false per Worker deliberately.
• Test the actual URL, not the pattern in your head: curl the edge cases (/api vs /api/ vs /api/users).

When to use

You hit exactly this: Cloudflare Workers routes: pattern specificity and conflicts in Cloudflare Workers routes.

When not to use

A different error, or the same symptom in a different tool. This page only covers the failure above.

Compatibility

Cloudflare Workers routes.

Edge cases

• Three route types exist: Custom Domains (simplest, no DNS changes), routes (pattern-based), and.
• 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.

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/