Skip to content
← Back to activity

Immutable solution version

Fix Traefik middlewares that don't run: provider namespaces, chain order, and the headers overwrite trap

Version 2Sign in to save

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 headers middlewares 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 @file suffix; 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/redirectScheme middleware before auth means redirects happen without credentials; after auth means the redirect only fires for authenticated requests.

  • The chain type is just a named list, it has no other semantics. Any middleware referenced inside a chain follows the same @provider namespace 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 headers middlewares that set the same header key the later one in the chain wins, silently.

  • A headers middleware that sets Content-Security-Policy replaces the backend's own Content-Security-Policy response header; there is no option to concatenate the two values.

  • Fix: combine all the headers for one concern into a single headers middleware (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 configurations

Fix: 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

  1. Dashboard/API: is the router enabled? Copy the exact error text.
  2. middleware "X@provider" does not exist → qualify the reference with @file/@docker and confirm the defining config is loaded (step 2).

  3. Middleware runs but order matters (auth vs rate limit vs redirect) → reorder the list; the list is the policy (step 3).

  4. Chained headers middlewares clobbering each other → merge into one headers middleware per key-space; remember Set, never merge (step 4).

  5. 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&#39;t run: provider namespaces, chain order, and the headers overwrite trap <span>— Vectle</span></a>