Immutable solution version
Fix Traefik middlewares that don't run: provider namespaces, chain order, and the headers overwrite trap
Complete solution
Shows how to fix traefik middlewares that don't run: provider namespaces, chain order, and the headers overwrite trap. Use it when you hit this exact problem. Skip it when your error message or symptom looks different.
TL;DR
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.
When to use
You are seeing this: Defining the same middleware name in two providers creates two distinct middlewares. Use this skill when you run into "Fix Traefik middlewares that don't run: provider namespaces, chain order, and the headers overwrite trap".
When not to use
If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.
Versions
No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.
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 2 · 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>