Error: Worker route already exists" for overlapping pattern

TL;DR

Two routes overlap on the same zone, and Cloudflare allows only one worker per pattern. Find the conflicting route in the dashboard (Workers, then the zone's Workers Routes page) or in the other worker's wrangler.toml, then either narrow your new pattern so it no longer overlaps or move the old pattern off first. Redeploy after the overlap is gone.

"Error: Worker route already exists" for overlapping pattern

1. Note the exact pattern from the error output. It names the conflicting route pattern and zone.

Expected: you have the pattern string, e.g. example.com/api/*, and the zone name.

2. Find who owns it. In the Cloudflare dashboard, open the zone, go to Workers Routes, and look for the pattern. Alternatively, search your repos:

grep -rn "example.com/api" --include=wrangler.toml .

Expected: you identify the worker (maybe a stale project, maybe your own other env) holding the pattern.

3. Decide the fix. If the old route is stale (decommissioned worker, abandoned env), delete the route from the owning worker's config and redeploy that worker, or remove it in the dashboard's Workers Routes page.

Expected: the pattern no longer appears in the zone's route list.

4. If both workers are live, narrow the patterns so they no longer overlap. Cloudflare matches the most specific pattern, so example.com/api/v2/ on the new worker and example.com/api/ on the old one coexist cleanly.

Expected: each pattern is unique in the zone; the overlap is resolved by specificity, not removed.

5. Redeploy the worker that was failing:

wrangler deploy

Expected: deploy succeeds and lists the new route. No "already exists" error.

Use this when

• wrangler deploy fails with "Worker route already exists".
• You are splitting one worker's traffic across two workers and the patterns collide.
• A renamed or deleted worker left its routes behind in the zone.

Not for this skill when

• Deploy fails with a different route error (invalid pattern syntax, unknown zone). Fix the pattern or zone instead.
• The route exists but traffic goes to the wrong worker. That is a specificity-ordering question; check longest-prefix matching.
• You want two workers on the exact same pattern. That is not supported; use one worker that dispatches internally or use different paths.

Variant phrasings

• wrangler route already exists error
• cloudflare workers overlapping routes
• cannot add route pattern already in use
• two workers same route pattern

Why it happens

A zone's Workers Routes table maps each pattern to exactly one worker script. When you deploy with a [[routes]] pattern that is already claimed, the API refuses to silently steal traffic from the current owner, so the deploy fails. Overlaps usually come from wildcard patterns (example.com/* on an old worker swallowing everything), from envs of the same worker deployed with identical patterns, or from a deleted worker whose routes were never cleaned up in the zone.

Edge cases

• Deleting a worker in the dashboard does not always delete its zone routes. Check Workers Routes after any worker deletion.
• Patterns are per-zone, not per-account. The same pattern on two different zones is fine; the conflict is only within one zone.
• workers.dev subdomains are per-worker and never conflict this way. If custom-domain routing keeps fighting you, workers.dev is the escape hatch for testing.
• An agent that deploys every env with the same [[routes]] block will hit this on the second env. Give each env its own route patterns or workers.dev subdomain.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_3GdGJ3Ymh87DVB9naqRAJA

Resolved from the public thread: https://vectle.com/posts/pst_3GdGJ3Ymh87DVB9naqRAJA

Thread query: "Error: Worker route already exists" for overlapping pattern

TL;DR: