Workers routes

Routes, Custom Domains and direct Workers URLs

A Workers route invokes a deployed Worker for requests that match a URL pattern on an existing proxied hostname. Use a route when the hostname already has an origin and the Worker should intercept or augment that traffic. Use a Workers Custom Domain when the Worker itself is the origin. A workers.dev address is useful for development and controlled direct access.

Prerequisites for a route

The zone must be active, the Worker must already be deployed, and the route hostname must have a proxied DNS record. The route stores a pattern and script association; it does not contain Worker code, bindings or secrets.

• Deploy and test the Worker independently before attaching production traffic.
• Confirm every binding and environment value used by the Worker.
• Keep a known-good Worker version available for rollback.

Route pattern syntax

Route patterns may contain wildcard characters but not regular expressions. The only wildcard is *, and it cannot be placed in the middle of a path segment as an arbitrary infix matcher. A scheme can be included or omitted. The host portion is normalized, while path matching is case-sensitive.

• example.com/* matches the apex host and every path.
• *.example.com/* matches subdomains but not the apex.
• *example.com/* can also match names such as myexample.com; use the dot form when only subdomains are intended.

Query strings and the trailing wildcard

Cloudflare evaluates the complete URL, including a query string. A route intended to accept arbitrary query parameters should normally end in *. Without the trailing wildcard, a URL that appears to have the same path can fail to match once ?name=value is present.

Overlapping routes and precedence

When several routes match, the most specific pattern wins. An empty-script route can negate a broader route for a narrower path. Inventory all existing patterns before adding one because a valid new route can silently shadow another Worker or exclude a path from execution.

• Test the intended matching path.
• Test a neighbouring path that must not match.
• Test with and without a query string and with path-case variations.

Origin pass-through and same-zone restrictions

A route Worker can call fetch() to continue to the origin. Avoid fetching a public URL covered by the same route, which can recursively invoke the Worker. A same-zone subrequest cannot target another route, while requests to Workers Custom Domains follow their separate routing behaviour. Routes take precedence over Custom Domains on a matching hostname.

Failure handling

Choose fail-open only when bypassing the Worker is safer than returning an error; choose fail-closed when the Worker enforces a security or correctness boundary that must never be skipped. CPU exhaustion commonly produces Worker error 1102. Route and request limits depend on plan, with a documented maximum number of routes per zone.

Validate a production route

Compare response status, headers, body, cache status and Worker logs for matching and non-matching URLs. Test redirects, large or streamed responses and an unavailable origin. A successful route save proves only that Cloudflare accepted the pattern; it does not prove the intended script handled the right traffic.

Rollback without creating another routing fault

Disable or remove the new route first so traffic returns to its previous path. If an older route was replaced, restore its exact pattern and script. Verify cached and uncached requests after rollback, then diagnose the Worker separately from the route.