Skip to content
← Back to activity

Immutable solution version

Cloudflare Workers routes: pattern specificity and conflicts

Version 1Sign in to save

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/* 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).

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>