Immutable solution version
Fix Traefik middlewares that don't run: provider namespaces, chain order, and the headers overwrite trap
Complete solution
Fix Traefik middleware failures by class: dead cross-provider references (middleware X@file does not exist), chain execution order (auth vs rate limit vs redirect), the headers middleware Set-not-merge overwrite trap, and Router defined multiple times conflicts.
When it applies
[{"constraint": ">=2.0", "technology": "Traefik", "version_scheme": "semver"}]
Fix Traefik middlewares that don't run: provider namespaces, chain order, and the headers overwrite trap
Use this when a Traefik middleware seems to do nothing, the dashboard shows the router disabled, or chaining two middlewares gives surprising results. Middleware failures fall into three distinct classes — a dead reference, a wrong order, or a merge that never happens — and each has a different fix.
1. Classify: dead reference, wrong order, or silent overwrite
Check the dashboard (or GET /api/http/routers) for your router:
Router disabled with an error like
middleware "authelia-forwardauth@file" does not exist→ dead reference. Go to step 2.Router enabled, middleware listed, but auth/redirect/rate-limit never triggers → the middleware is attached to the wrong router, or a chain runs in an unexpected order. Go to step 3.
Router enabled, two
headersmiddlewares chained, but only one set of headers appears on the response → the headers overwrite trap. Go to step 4.Error
Router defined multiple times with different configurations→ the same router name is defined on two containers with different middleware lists. Go to step 5.
2. Dead reference: the @provider namespace
Every middleware lives in a provider namespace, and a bare name resolves in the router's own provider. A router built from Docker labels that references a middleware defined in the file provider must qualify it:
# WRONG: resolves to authelia@docker, which does not exist -> router disabled
- "traefik.http.routers.myapp.middlewares=authelia"
# RIGHT: the middleware is defined in the file provider
- "traefik.http.routers.myapp.middlewares=authelia@file"Rules:
From Docker labels, file-provider middlewares need the
@filesuffix; Docker-defined middlewares referenced from the file provider need@docker.The error names the exact missing reference (
middleware "authelia-forwardauth@file" does not exist) — trust it and check that the defining file is actually loaded (mounted, valid YAML, watched by the file provider).Middleware names are global within a provider. Defining the same middleware name in two providers creates two distinct middlewares.
3. Order: chains run in list order on the request path
Middlewares listed on a router execute in the order they are listed for the request; a chain middleware runs its members in its own list order. Response-side effects (response headers) apply in reverse as the response unwinds.
# request passes simple_ratelimit first, then digest_auth, then the service
- "traefik.http.middlewares.secured_chain.chain.middlewares=simple_ratelimit,digest_auth"
- "traefik.http.middlewares.simple_ratelimit.ratelimit.average=5"
- "traefik.http.middlewares.simple_ratelimit.ratelimit.period=5s"
- "traefik.http.middlewares.simple_ratelimit.ratelimit.burst=2"
- "traefik.http.routers.whoami_route.middlewares=secured_chain"Practical consequences:
Put auth before rate limiting if unauthenticated requests shouldn't consume quota — or rate limit first if you want to blunt brute force. The choice is yours, but it must be deliberate: list order is the policy.
A
redirectRegex/redirectSchememiddleware before auth means redirects happen without credentials; after auth means the redirect only fires for authenticated requests.The
chaintype is just a named list — it has no other semantics. Any middleware referenced inside a chain follows the same@providernamespace rule as step 2.
4. The headers overwrite trap: Set, not merge
The headers middleware applies Go's header Set semantics: for each configured header it overwrites any existing value. It never appends and never merges. Consequences that bite people:
Two chained
headersmiddlewares that set the same header key — the later one in the chain wins, silently.A
headersmiddleware that setsContent-Security-Policyreplaces the backend's ownContent-Security-Policyresponse header; there is no option to concatenate the two values.Fix: combine all the headers for one concern into a single
headersmiddleware (one global security-headers middleware, one per-service middleware only when its keys are disjoint), e.g.:
# file provider: one middleware holding all security headers
http:
middlewares:
secure-headers:
headers:
stsSeconds: 31536000
stsIncludeSubdomains: true
stsPreload: true
contentTypeNosniff: true
referrerPolicy: "strict-origin-when-cross-origin"
customResponseHeaders:
X-Robots-Tag: "none,noarchive"The dashboard showing both middlewares as "enabled, no errors" does not contradict this — both run; the later Set simply wins.
5. Router defined multiple times
Middlewares attach to a router, not a host. If two containers define the same router name (traefik.http.routers.backend...) with different middleware lists, Traefik rejects the conflict:
Router defined multiple times with different configurationsFix: give each container's router a unique name (traefik.http.routers.backend1, traefik.http.routers.backend2), each with its own middleware list. Containers behind one router must share the identical router configuration, including middlewares.
6. Checklist
- Dashboard/API: is the router enabled? Copy the exact error text.
middleware "X@provider" does not exist→ qualify the reference with@file/@dockerand confirm the defining config is loaded (step 2).Middleware runs but order matters (auth vs rate limit vs redirect) → reorder the list; the list is the policy (step 3).
Chained
headersmiddlewares clobbering each other → merge into oneheadersmiddleware per key-space; rememberSet, never merge (step 4).Router defined multiple times→ unique router names per container, middleware lists identical per router (step 5).
Evidence
Built from the Traefik provider-namespace documentation, the chain middleware reference, the headers middleware source behavior (Set/delete, no merge) confirmed by community threads, and real dashboard error strings (middleware does not exist, Router defined multiple times with different configurations).
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_gFj2jnSl94SVovFE4Egkbg" 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">Fix Traefik middlewares that don't run: provider namespaces, chain order, and the headers overwrite trap <span>— Vectle</span></a>