$ guides / traefik / traefik-router-priority-conflict ▌

Operations Guides

Traefik router priority conflicts: when overlapping rules match the wrong service

Traffic for api.example.com is landing on your generic dashboard service instead of the API backend. Or you deployed a new router with what looks like a correct rule, and it never matches a single request. Traefik is up, /ping returns 200, there are no errors in the logs, and the config reload metric keeps advancing. Everything looks healthy except the routing decision itself.

This is almost always a router priority conflict. When two routers have overlapping rules, Traefik does not pick the most specific match by semantics. It sorts routers by a numeric priority, and the first one whose rule matches wins. The default priority is the length of the rule string, not the specificity of the rule. A longer but broader rule will shadow a shorter, more specific one.

The failure is silent. Traefik does not log “router X shadowed router Y.” The losing router never matches, and the winning router sends traffic to its own service, which may respond with perfectly valid 200s for the wrong content.

What this means

Traefik evaluates routers in priority order. By default, the priority equals the length of the rule string: the longest rule has the highest priority. When two rules overlap (both could match the same request), the higher-priority one wins and the other is never consulted for that request.

The trap is that string length is a proxy for specificity, and a bad one in several common cases:

A HostRegexp rule is usually longer than an equivalent Host rule, so the regexp wins by default even when the exact host rule is what you intended.
A broad catch-all combined with a PathPrefix can be longer than a precise Host rule for a specific service.
Two rules of similar length on overlapping domains produce an ordering that is deterministic but not the one you expect.

You can override the computed priority by setting an explicit priority on the router. An explicit value always beats the computed rule-length value.

flowchart TD
  A[Incoming request] --> B{TCP router matches?}
  B -- yes --> C[TCP router handles it, HTTP never evaluated]
  B -- no --> D[HTTP routers sorted by priority desc]
  D --> E{Router 1 rule matches?}
  E -- yes --> F[Router 1 service handles request]
  E -- no --> G{Router 2 rule matches?}
  G -- yes --> H[Router 2 service handles request]
  G -- no --> I[...down the priority list...]
  I -- none match --> J[Traefik returns 404 at entrypoint]

Two more ordering facts worth knowing before you debug:

If TCP and HTTP routers share an entrypoint, TCP routers are evaluated first. If a TCP router matches, the HTTP routers are never consulted.
When two routers from different providers end up with the same numeric priority, the providers.precedence static option introduced in v3.7.0 breaks the tie. It is only a tiebreaker; an explicit router priority always beats it.

Common causes

Cause	What it looks like	First thing to check
Longer regexp rule shadows exact Host rule	Requests for a specific host land on the regexp router’s service	Compare computed priorities of both routers via the API
Broad catch-all shadows specific rule	New, more specific router never matches; all traffic hits the catch-all	Look for `PathPrefix("/")` or host-wide rules with long combined rule strings
Equal explicit priorities on overlapping routers	Ordering falls back to rule length within the equal-priority group, not to what you intended	Check whether both routers have the same `priority` value
v2 to v3 migration changed rule interpretation	A router that never matched under v2 starts matching (and winning) under v3	Check whether a `HostRegexp` rule changed behavior after the upgrade
TCP router on shared entrypoint shadows HTTP routers	HTTP router never matches despite a correct rule	List TCP routers bound to the same entrypoint
Rule silently not loaded	Router does not exist in Traefik’s view at all (annotation or label rejected)	Confirm the router appears in `/api/http/routers`

Quick checks

These are read-only and safe to run during an incident.

# List all HTTP routers with their rules and resolved priorities (Traefik v3)
curl -s http://localhost:8080/api/http/routers | \
  jq -r '.[] | "\(.priority)\t\(.name)\t\(.rule)\t-> \(.service)"' | sort -rn

The priority field in the API response is the single most useful debugging datum here. It shows the value Traefik actually computed, not the value you think it computed. The API exposes the embedded router configuration in both current v2 and v3; the distinction is that v3 also exposes a string form named priorityStr.

# Inspect one specific router in detail
curl -s http://localhost:8080/api/http/routers/my-router@docker | jq .

# List TCP routers on the same entrypoint (they are evaluated before HTTP)
curl -s http://localhost:8080/api/tcp/routers | \
  jq -r '.[] | "\(.name)\t\(.rule)\tentrypoints=\(.entryPoints)"'

# Check entrypoint-level 404s: requests that matched no router at all
curl -s http://localhost:8080/metrics | grep 'traefik_entrypoint_requests_total.*code="404"'

# Confirm config is fresh (stale config can mimic a routing bug)
curl -s http://localhost:8080/metrics | grep traefik_config_last_reload_success

On the 404 check: if your symptom is “requests go to the wrong service,” the entrypoint 404 rate will be flat because a router did match. Rising entrypoint 404s point at a different problem, requests matching no router at all. See Traefik 404 not found: requests arriving with no matching router for that case.

How to diagnose it

Reproduce the misrouting deterministically. Send a request with an explicit Host header and path, and confirm which service responds: curl -sv -H "Host: api.example.com" http://traefik-address/path. Check response headers or backend logs to see which service actually handled it.
Pull the live routing table. Query /api/http/routers and find every router whose rule could match your test request. Do not stop at the first one; list all candidates.
Sort candidates by resolved priority. The router at the top of that list is the one handling your traffic. If it is not the router you intended, you have found the conflict.
Compute what the default priorities would be. For each candidate rule, count the rule string length; the longest string wins by default. Worked example: HostRegexp([a-z]+.traefik.com) has length 32 and beats Host(foobar.traefik.com) at length 26, even though the exact host rule is the one most operators intend to win.
Check for explicit priorities and equal values. If two overlapping routers have explicit priority set to the same number, Traefik falls back to rule-length ordering within that equal-priority group. Setting priority: 10 on both does not make “the more specific one” win; it reintroduces length-based ordering between them.
Check the entrypoint binding. Confirm both routers are on the entrypoint you are testing, and check whether any TCP router on that entrypoint could match first. A matching TCP router ends evaluation before any HTTP router runs.
Rule out staleness and silent rejection. If the router you expect is missing from the API entirely, this is not a priority conflict. Check traefik_config_last_reload_success freshness and look for rejected annotations or labels; Traefik silently ignores unknown or misspelled ones. See Traefik config last reload success: monitoring configuration freshness.
If nothing explains it, suspect a provider-level bug. There is an active, unresolved Gateway API issue (traefik/traefik#12795). Without a listener hostname, a specific-hostname HTTPRoute gets a higher priority and should beat a catch-all. With an exact listener hostname, the listener/HTTPRoute hostname intersection can give both routes the same generated rule and priority; the missing deterministic tie-break can then make the older catch-all win. A user-reported workaround for that listener-hostname case is removing the listener hostname and managing certificates explicitly. If you are on the Gateway API provider and your explicit priorities look correct, check the open issue tracker before assuming your config is wrong.

Metrics and signals to monitor

Signal	Why it matters	Warning sign
`traefik_service_requests_total` per service	A shadowed router means one service gets traffic meant for another	Traffic shifts between services right after a config change, with no deploy on either service
`traefik_entrypoint_requests_total{code="404"}`	Distinguishes “no router matched” from “wrong router matched”	Rising 404s alongside a misrouting complaint suggests a missing router, not a priority conflict
`traefik_config_last_reload_success`	Confirms the routing table you are debugging is the one Traefik is actually running	Timestamp frozen while you are actively deploying route changes
Per-router request metrics (`addRoutersLabels: true`)	Shows exactly which router matched, making shadowing visible as zero traffic on the intended router	A router with a valid rule showing zero requests while an overlapping router absorbs them; note the cardinality cost of router labels
`traefik_config_reloads_total`	Every priority change triggers a reload; correlates routing changes with traffic shifts	Traffic redistribution coinciding with a reload event

Fixes

Set explicit priorities on the specific router

Give the more specific router an explicit priority higher than any competing rule’s computed length. Rule lengths are small numbers (tens of characters), so a value like 100 or 1000 gives you clear headroom:

# File provider example: exact host wins over a broader regexp or catch-all
http:
  routers:
    api-exact:
      rule: "Host(`api.example.com`)"
      service: api-service
      priority: 100
    api-catchall:
      rule: "HostRegexp(`[a-z]+.example.com`)"
      service: generic-service
      # no explicit priority: computed from rule length, stays below 100

Traefik reserves a range of high priorities for internal routers; the documented maximum user-defined priority is (MaxInt32 - 1000) on 32-bit platforms and (MaxInt64 - 1000) on 64-bit platforms, so values in the hundreds or thousands are always safe. Negative priorities are also supported and push a router below the default computed priorities, which is useful for demoting a catch-all without touching every other router.

Tradeoff: explicit priorities are a maintenance contract. Every future router that overlaps must be evaluated against the explicit values, not just the rule strings. Document the priority scheme somewhere near the config.

Use distinct explicit priorities, not equal ones

If you set priorities on overlapping routers, make them different. Equal explicit priorities fall back to rule-length sorting within that group, which recreates the ambiguity you were trying to remove.

Note on priority: 0

A priority of 0 is ignored. It does not mean “lowest priority”; it means “use the default rule-length computation.” If you want a router demoted below all default priorities, use a negative value, not zero.

Narrow the catch-all itself

Often the cleanest fix is to make the broad rule stop overlapping. A HostRegexp or wildcard rule that excludes the specific subdomain (or a catch-all constrained to paths the specific router does not serve) removes the conflict without any priority arithmetic. This is more robust than priorities because it keeps working when someone later adds another router without knowing about your priority scheme.

After a v2 to v3 migration

The priority computation itself did not change between v2 and v3, but v3 correctly parses some regex patterns that v2 silently mishandled. A HostRegexp that never matched under v2 can start matching under v3 and overtake a previously winning Host router. If routing behavior changed right after an upgrade with no config edits, audit every HostRegexp rule’s resolved priority and traffic share. Wildcard subdomain matching with *.example.com also requires v3 rule syntax.

Prevention

Audit overlaps at deploy time. Any new router whose rule can match the same requests as an existing router needs an explicit priority decision. A short review checklist item catches most of these.
Prefer non-overlapping rules. Design rules so each request matches exactly one router. Priorities then become a safety net instead of load-bearing config.
Reserve a priority band convention. For example: 100+ for exact-host production services, 50-99 for environment or staging rules, below 50 (or negative) for catch-alls and fallbacks. Conventions prevent the “two routers both set to 10” trap.
Watch traffic share after every routing change. A priority conflict manifests as a traffic shift between services at the moment of a config reload. Alerting on sudden per-service traffic redistribution after traefik_config_reloads_total increments catches this in minutes instead of after a user report.
Snapshot /api/http/routers periodically. The resolved priority list is ground truth. Diffing it before and after changes shows exactly which ordering shifted.

How Netdata helps

Per-service request rate breakdown from traefik_service_requests_total makes shadowing visible as a traffic shift between services, which is the signature of a priority conflict rather than a backend failure.
Entrypoint-level 404 tracking (traefik_entrypoint_requests_total{code="404"}) separates “no router matched” from “wrong router matched,” so you start the right investigation path immediately.
Config reload freshness (traefik_config_last_reload_success) and reload count (traefik_config_reloads_total) let you correlate the moment a routing change landed with the moment traffic moved.
Per-second collection catches brief shadowing windows during rolling deployments or config flapping that minute-resolution scrapes miss.
Anomaly detection on per-service traffic flags an unexpected redistribution even when total traffic is unchanged, which is the pattern a priority swap produces: one service down, another up, totals flat.