Traefik v2 to v3 Migration: Breaking Changes and Steps (2026)

Traefik v3 is a significant upgrade from v2, and while it brings many improvements, migrating requires careful attention to several breaking changes. The primary shift is a more robust and opinionated configuration structure, particularly around how providers and entrypoints are defined, and a tightened security posture that may break existing TLS setups.

Here’s a breakdown of the key changes and how to navigate them:

Entrypoints and Listeners

In v2, entryPoints were implicitly tied to the serversTransport configuration. v3 separates these concerns, requiring explicit configuration for both.

The Problem: Your existing Traefik configuration likely defines entrypoints like this:

entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"

This will fail in v3 because the serversTransport is no longer implicitly linked.

Diagnosis: Check your Traefik logs for errors related to missing or invalid serversTransport configurations when defining entrypoints. You might see messages like:

level=error msg="failed to create server transport: tls.certificates is not set" entryPointName=websecure

Cause 1: Implicit serversTransport Removed

Diagnosis: Run traefik --config.file=/path/to/traefik.yml and observe startup errors.

Fix: Explicitly define your serversTransport for TLS-enabled entrypoints. Even if you’re not doing anything fancy, you need a default.

entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"
    http:
      tls: {} # This implicitly uses the default serversTransport

# You might need to explicitly define a default serversTransport if you were relying on implicit behavior
# serversTransports:
#   default: {}

Why it works: v3 enforces that TLS configurations must have an associated serversTransport defined, preventing implicit assumptions and making the configuration more explicit and secure.

Cause 2: Default TLS Certificate Handling

Diagnosis: If you previously relied on Traefik automatically picking up a default TLS certificate (e.g., from Let’s Encrypt via ACME), this behavior has changed.

Fix: Explicitly configure your TLS options and certificates.

entryPoints:
  websecure:
    address: ":443"
    http:
      tls:
        certResolver: myresolver # Assuming you have an ACME resolver named 'myresolver'
        # If you have a specific certificate file, you'd configure it here
        # certs:
        #   - cert: /path/to/your.crt
        #     key: /path/to/your.key

Why it works: v3 requires you to declare how TLS certificates are managed, whether through a resolver like ACME or by providing specific files, making the TLS setup more deliberate.

Router Rules and Middleware Matching

The way router rules and middleware are matched has been refined. Specifically, the Host rule is now more strict, and the evaluation order of middleware can have different implications.

The Problem: Routers that relied on wildcard host matching or specific rule syntax might stop working.

Cause 3: Stricter Host Rule Matching

Diagnosis: Check logs for level=error msg="unable to find any router for the given request" or similar messages when requests to specific hosts fail.

Fix: Ensure your Host rules are precise. For example, Host(example.com) will only match example.com, not www.example.com. If you need subdomains, use wildcards explicitly: Host({subdomain:[a-z0-9-]+}.example.com).

# v2 might have worked with this implicitly for subdomains
# routers:
#   myrouter:
#     rule: "Host(`example.com`)"

# v3 requires explicit wildcard matching for subdomains
routers:
  myrouter:
    rule: "Host(`{subdomain:[a-z0-9-]+}.example.com`)"
    service: myservice

Why it works: v3’s Host rule is more literal. Using the {subdomain:[a-z0-9-]+} pattern allows Traefik to correctly parse and match subdomains based on defined character sets.

Cause 4: Middleware Order and Dependencies

Diagnosis: Services that previously worked might now return errors or unexpected responses, often related to authentication or header manipulation.
Fix: Review the order of middleware in your router definitions. Middleware is applied sequentially. Ensure that middleware requiring specific headers or context are placed after middleware that provides them.
```
routers:
  myrouter:
    rule: "Host(`example.com`)"
    service: myservice
    middlewares:
      - auth@file # Example: Authentication middleware
      - headers@file # Example: Header modification middleware
```
If headers@file modifies a header that auth@file needs, the order should be reversed.
Why it works: Traefik v3 has a more deterministic middleware execution pipeline. The order in which middleware is listed in the router configuration dictates the order of application, and dependencies between middleware must be respected.

API and Dashboard Access

Access to the Traefik API and Dashboard has been secured by default.

The Problem: If you previously accessed the API/Dashboard without authentication, it will now be blocked.

Cause 5: API and Dashboard Security Enabled by Default

Diagnosis: Attempting to access http://traefik-ip:8080/dashboard/ or /api/ returns a 404 Not Found or 403 Forbidden error.

Fix: Explicitly enable and configure access, or disable security if you understand the risks.

# Enable API and Dashboard
api:
  dashboard: true
  insecure: true # Use with caution, or configure proper authentication

# Or, for secure access (recommended):
# api:
#   dashboard: true
#   debug: true
#
# providers:
#   ...
#
# entryPoints:
#   traefik:
#     address: ":8080"
#
# routers:
#   dashboard:
#     rule: "Host(`traefik.example.com`)"
#     service: api@internal
#     middlewares:
#       - auth@file # Add your authentication middleware here

Why it works: v3 prioritizes security. By default, the API and Dashboard are not exposed insecurely. You must opt-in to insecure access or configure secure access with appropriate routing and authentication.

Dynamic Configuration Providers

Changes in how providers are configured can also lead to issues.

Cause 6: Kubernetes CRD Provider Changes

Diagnosis: If you use the Kubernetes CRD provider, check for errors related to IngressRoute or Middleware CRDs not being recognized or applied.
Fix: Update your Kubernetes manifests to use the v1 API versions for Traefik CRDs. The specific CRD versions might have changed. Consult the v3 migration guide for the exact versions.
```
# Example: IngressRoute CRD version might change from traefik.io/v1alpha1 to traefik.io/v1
apiVersion: traefik.io/v1 # Or the new version
kind: IngressRoute
# ...
```
Why it works: Kubernetes CRDs are versioned. Traefik v3 often uses updated or new API versions for its CRDs to accommodate new features and structural changes, requiring manifest updates.

General Migration Steps

Backup: Always back up your Traefik configuration files and any associated data (like ACME certificates).
Read Release Notes: Thoroughly review the official Traefik v3 release notes and migration guide. They are the definitive source for all breaking changes.
Staging Environment: Test your migration in a staging or development environment that mirrors your production setup.
Incremental Updates: If possible, update components that depend on Traefik (e.g., your applications) incrementally.
Monitor Logs: Closely monitor Traefik logs during and after the migration for any new errors or warnings.

After fixing these issues, the next problem you’ll likely encounter is related to Traefik’s new default behavior of requiring explicit configuration for all entrypoints, even those that don’t use TLS, leading to potential "invalid configuration" errors if http or tcp configurations are missing.

Entrypoints and Listeners

Router Rules and Middleware Matching

API and Dashboard Access

Dynamic Configuration Providers

General Migration Steps

More Deep Dives in Traefik