$ guides / traefik / traefik-route-not-loading ▌

Operations Guides

Traefik route not loading: silently ignored annotations and labels

You deployed a service, added the Traefik annotations or labels, and the route does not work. Requests to the hostname return 404. Traefik is up, other routes work, the provider is connected, and there is no error anywhere in the logs. The service simply does not exist as far as Traefik is concerned.

This is silent rejection: Traefik ignores any annotation or label key it does not recognize. A wrong prefix, a misspelled key, a label at the wrong YAML level, or a value mangled by YAML parsing all produce the same outcome: the route is never created, no error metric is emitted, and nothing is logged at the default log level. The configuration you wrote and the configuration Traefik loaded diverge without either side complaining.

This is distinct from provider desync, where Traefik loses connectivity to the provider entirely. Here the provider is connected and reloading fine; Traefik read your object and discarded the parts it did not understand.

What this means

Traefik builds its routing table by reading objects from providers: Ingress resources in Kubernetes, container labels in Docker, service labels in Swarm. For each object, it walks a fixed set of recognized keys. Anything outside that set is skipped. There is no schema validation step that rejects an unknown key, no warning log at default levels, and no metric counting rejected configuration.

Two different “my route does not exist” problems look identical from the outside:

Provider problem: Traefik never saw your object (RBAC denied, socket unreachable, watch broken). The config reload timestamp stops advancing. See Traefik 404 not found: requests arriving with no matching router for the provider desync path.
Silent rejection: Traefik saw your object, parsed it, and ignored the keys it did not recognize. Config reloads keep succeeding. The timestamp advances. The router is just absent.

The second case is the subject here. The tell: traefik_config_last_reload_success keeps advancing after your deployment, yet the router never appears.

Common causes

Cause	What it looks like	First thing to check
Wrong annotation or label prefix	Router absent; key uses an outdated or invented prefix (for example a v1-era prefix on v3)	Compare your key against the recognized list for your provider in the Traefik reference docs
Misspelled key	Router absent; one character off in a long dotted key	Diff the object’s keys against a known-good service’s keys
Label at the wrong YAML level (Swarm)	Service deployed, no router, no error	Confirm labels are inside the `deploy:` block, not at the service level
YAML type coercion	Label value parsed as boolean or number instead of string	`docker inspect` the container and look at what Docker actually stored
Backticks stripped from rule values	`Host()` rule silently broken; router missing or malformed	Quote the entire label value; verify the stored value via `docker inspect`
`traefik.enable` missing or misplaced	Container invisible to Traefik when `exposedByDefault=false`	Check the label exists as a container label, not an environment variable
Removed or renamed key after upgrade	Route worked before the Traefik upgrade, gone after	Check the deprecation and migration notes for your version jump
Duplicate router name (Swarm)	One of two services with the same router name is ignored	Search all stacks for the router name

Quick checks

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

# 1. What routers did Traefik actually load?
curl -s http://localhost:8080/api/http/routers | jq '.[] | {name, rule, status, provider}'

The API is the ground truth. If your router is not in this output, Traefik never built it, regardless of what your manifests say.

# 2. Did config reloads keep succeeding after your deploy?
curl -s http://localhost:8080/metrics | grep traefik_config_last_reload_success
curl -s http://localhost:8080/metrics | grep traefik_config_reloads_total

An advancing timestamp and incrementing counter mean the provider is healthy and this is a per-object rejection, not a desync.

# 3. What labels did Docker actually store on the container?
docker inspect <container> --format '{{json .Config.Labels}}' | jq .

This shows the post-YAML-parsing truth, which is what Traefik reads. Quote-stripping and type coercion bugs are visible here and invisible in your compose file.

# 4. What annotations are on the Ingress?
kubectl get ingress <name> -n <ns> -o jsonpath='{.metadata.annotations}' | jq .

# 5. Are clients hitting entrypoint-level 404s?
curl -s http://localhost:8080/metrics | grep 'traefik_entrypoint_requests_total' | grep 'code="404"'

Entrypoint 404s mean “no router matched,” which is consistent with a route that never loaded. Service-level 404s come from backends and mean something different.

How to diagnose it

The workflow is a diff: intended configuration versus loaded configuration.

Establish that the provider is fine. Check traefik_config_last_reload_success. If the timestamp advanced after you deployed the object, Traefik processed the event. If it is frozen, stop here and treat it as provider desync instead.
Pull the loaded routing table. Query /api/http/routers and search for the router name you expect. Note the naming convention: Docker and Swarm routers are suffixed with the provider (for example myapp@docker), so search by substring rather than exact match.
If the router exists but the rule is wrong, the keys were recognized but the values were mangled. This is the YAML parsing class of bugs: stripped backticks in Host() rules, booleans coerced from unquoted strings. Inspect the stored labels or annotations directly (checks 3 and 4 above) and compare character-for-character with what you wrote.
If the router is absent, the object was read and every routing key on it was ignored, or the object was excluded entirely. Check, in order:
- Is traefik.enable=true present (as a string label, not an env var) when your provider has exposedByDefault=false?
- For Swarm: are the labels under deploy:, not at the service level?
- Does every key exactly match the recognized set for your Traefik major version? A prefix from an older major version or a blog post is a common culprit.
- After a recent Traefik upgrade: was the key you rely on deprecated or removed? For example, the Kubernetes Ingress API version networking.k8s.io/v1beta1 is not supported in Traefik v3; objects using it are ignored.
Fix one thing and re-check the API. The reload is automatic; the router should appear in /api/http/routers within seconds of a valid change. If it does not, you have a second, distinct problem.

flowchart TD
    A[Route not working] --> B{Router in /api/http/routers?}
    B -->|Yes, rule wrong| C[Compare stored labels/annotations against source YAML - quoting and type coercion]
    B -->|No| D{Config reload timestamp advancing?}
    D -->|No| E[Provider desync - different incident]
    D -->|Yes| F[Diff object keys against recognized set for this Traefik version]
    F --> G{Key problems found?}
    G -->|Yes| H[Fix prefix/spelling/level, re-check API]
    G -->|No| I[Check traefik.enable, Swarm deploy block, upgrade deprecations]

Metrics and signals to monitor

Signal	Why it matters	Warning sign
`traefik_entrypoint_requests_total{code="404"}`	Entrypoint 404s mean no router matched, the client-visible symptom of a route that never loaded	Sustained rate above 5% of entrypoint requests, or a step increase right after a deployment
`traefik_config_last_reload_success`	Distinguishes silent rejection (advancing) from provider desync (frozen)	Frozen timestamp in an actively changing environment
`traefik_config_reloads_total`	Confirms Traefik is processing provider events	Counter stops incrementing
Router count in `/api/http/routers`	The direct measure of what loaded	Count unchanged after deploying a new routed service

The critical correlation: a deployment event followed by an unchanged router count and rising entrypoint 404s, while config reloads keep succeeding. That triad is silent rejection, not desync.

Fixes

Wrong or misspelled key. Correct the key against the reference for your provider and major version. The complete recognized sets are documented at doc.traefik.io: the Kubernetes Ingress annotations table and the Docker labels table are the authoritative lists. Anything not in those tables is ignored. Do not trust third-party tutorials for key names; they frequently mix major versions.

YAML quoting and coercion. Quote all label values, especially anything containing backticks, colons, or the word true. In Docker Compose, traefik.enable: 'true' (quoted string) is safe; an unquoted value can be parsed as a boolean and silently dropped. Verify the fix with docker inspect, not by re-reading your compose file.

Swarm label placement. Move labels into the deploy: section of the service. Also audit router names for uniqueness across all stacks; Traefik resolves name collisions by picking one and ignoring the other, with no warning.

Missing traefik.enable. Add it as a container label when exposedByDefault=false. If your team uses UIs like Portainer, confirm the value landed as a label rather than an environment variable; this mix-up is common.

Upgrade deprecations. When a route vanishes after a Traefik upgrade, consult the migration notes for your version jump rather than debugging the object. Keys and behaviors are removed between major versions, and the failure mode is the same silent absence.

Prevention

Diff the API in CI. After a config change, assert that the expected router name appears in /api/http/routers. This turns a silent failure into a pipeline failure.
Template and lint your keys. Generate labels and annotations from a shared template per Traefik major version instead of hand-writing them per service. Most silent rejections are typos or stale prefixes copied between services.
Alert on entrypoint 404s correlated with deploys. A step change in traefik_entrypoint_requests_total{code="404"} within minutes of a deployment is a strong, cheap signal of a route that failed to load.
Pin doc references to your major version. Keep a link to the recognized annotation/label table for the version you run in your team runbook.
Restrict the dashboard and API port. Everything in this article assumes you can reach :8080. Keep it internal-only; the same API that helps you diagnose exposes your full routing table.

How Netdata helps

Netdata charts traefik_config_last_reload_success over time, so you can see whether reloads kept advancing through your deploy, separating silent rejection from provider desync in seconds.
Entrypoint request counts broken down by response code surface the 404 step change that follows a route failing to load, and let you correlate it against the deploy timeline on the same dashboard.
Because Netdata collects per-second, the gap between “deployed” and “404s started” is visible precisely, which matters when you are deciding whether the cause is your change or an unrelated provider issue.
Alerts on the ratio of entrypoint 404s to total requests catch silently dropped routes even when no one is watching the dashboard, since Traefik itself emits no error for this failure mode.