Skip to content

Errors

The Errors middleware returns a custom page in lieu of the default, according to configured ranges of HTTP Status codes.

Important

The error page itself is not hosted by Traefik Enterprise.

Configuration Examples

# Dynamic Custom Error Page for 5XX Status Code
labels:
  - "traefik.http.middlewares.test-errors.errors.status=500,501,503,505-599"
  - "traefik.http.middlewares.test-errors.errors.service=serviceError"
  - "traefik.http.middlewares.test-errors.errors.query=/{status}.html"
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-errors
spec:
  errors:
    status:
      - "500"
      - "501"
      - "503"
      - "505-599"
    query: /{status}.html
    service:
      name: whoami
      port: 80
# Dynamic Custom Error Page for 5XX Status Code excluding 502 and 504
- "traefik.http.middlewares.test-errors.errors.status=500,501,503,505-599"
- "traefik.http.middlewares.test-errors.errors.service=serviceError"
- "traefik.http.middlewares.test-errors.errors.query=/{status}.html"
"labels": {
  "traefik.http.middlewares.test-errors.errors.status": "500,501,503,505-599",
  "traefik.http.middlewares.test-errors.errors.service": "serviceError",
  "traefik.http.middlewares.test-errors.errors.query": "/{status}.html"
}
# Dynamic Custom Error Page for 5XX Status Code excluding 502 and 504
labels:
  - "traefik.http.middlewares.test-errors.errors.status=500,501,503,505-599"
  - "traefik.http.middlewares.test-errors.errors.service=serviceError"
  - "traefik.http.middlewares.test-errors.errors.query=/{status}.html"
# Dynamic Custom Error Page for 5XX Status Code excluding 502 and 504
http:
  middlewares:
    test-errors:
      errors:
        status:
          - "500"
          - "501"
          - "503"
          - "505-599"
        service: serviceError
        query: "/{status}.html"

  services:
    # ... definition of error-handler-service and my-service
# Dynamic Custom Error Page for 5XX Status Code excluding 502 and 504
[http.middlewares]
  [http.middlewares.test-errors.errors]
    status = ["500","501","503","505-599"]
    service = "serviceError"
    query = "/{status}.html"

[http.services]
  # ... definition of error-handler-service and my-service

In this example, the error page URL is based on the status code (query=/{status}.html).

Configuration Options

status

The status option defines which status or range of statuses should result in an error page.

The status code ranges are inclusive (505-599 will trigger with every code between 505 and 599, 505 and 599 included).

You can define either a status code as a number (500), as multiple comma-separated numbers (500,502), as ranges by separating two codes with a dash (505-599), or a combination of the two (404,418,505-599). The comma-separated syntax is only available for label-based providers. The examples above demonstrate which syntax is appropriate for each provider.

service

The service that will serve the new requested error page.

In Kubernetes, you need to reference a Kubernetes Service instead of a Traefik service.

Host Header

By default, the client Host header value is forwarded to the configured error service. To forward the Host value corresponding to the configured error service URL, the passHostHeader option must be set to false.

query

The URL for the error page (hosted by service)).

There are multiple variables that can be placed in the query option to insert values in the URL.

The table below lists all the available variables and their associated values.

Variable Value
{status} The response status code.
{url} The escaped request URL.

ignorebackenderrors

This option allows you to ignore backend errors. For example, if you configure status to be in the range 505-599, and your backend sends one of these error codes, the response will be the one from your backend. But if it's Traefik Enterprise sending one of these errors, then the error page will be the one hosted by the service.