ErrorPage

It Has Never Been Easier to Say That Something Went Wrong

ErrorPages

The ErrorPage 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.

Configuration Examples

Docker

  1. # Dynamic Custom Error Page for 5XX Status Code
  2. labels:
  3.   - "traefik.http.middlewares.test-errorpage.errors.status=500-599"
  4.   - "traefik.http.middlewares.test-errorpage.errors.service=serviceError"
  5.   - "traefik.http.middlewares.test-errorpage.errors.query=/{status}.html"

Kubernetes

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: Middleware
  3. metadata:
  4.   name: test-errorpage
  5. spec:
  6.   errors:
  7.     status:
  8.       - 500-599
  9.     query: /{status}.html
  10.     service:
  11.       name: whoami
  12.       port: 80

Consul Catalog

  1. # Dynamic Custom Error Page for 5XX Status Code
  2. - "traefik.http.middlewares.test-errorpage.errors.status=500-599"
  3. - "traefik.http.middlewares.test-errorpage.errors.service=serviceError"
  4. - "traefik.http.middlewares.test-errorpage.errors.query=/{status}.html"

Marathon

  1. "labels": {
  2.   "traefik.http.middlewares.test-errorpage.errors.status": "500-599",
  3.   "traefik.http.middlewares.test-errorpage.errors.service": "serviceError",
  4.   "traefik.http.middlewares.test-errorpage.errors.query": "/{status}.html"
  5. }

Rancher

  1. # Dynamic Custom Error Page for 5XX Status Code
  2. labels:
  3.   - "traefik.http.middlewares.test-errorpage.errors.status=500-599"
  4.   - "traefik.http.middlewares.test-errorpage.errors.service=serviceError"
  5.   - "traefik.http.middlewares.test-errorpage.errors.query=/{status}.html"

File (TOML)

  1. # Custom Error Page for 5XX
  2. [http.middlewares]
  3.   [http.middlewares.test-errorpage.errors]
  4.     status = ["500-599"]
  5.     service = "serviceError"
  6.     query = "/{status}.html"
  8. [http.services]
  9.   # ... definition of error-handler-service and my-service

File (YAML)

  1. # Custom Error Page for 5XX
  2. http:
  3.   middlewares:
  4.     test-errorpage:
  5.       errors:
  6.         status:
  7.           - "500-599"
  8.         service: serviceError
  9.         query: "/{status}.html"
  11. [http.services]
  12.   # ... 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 that will trigger the error page.

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

You can define either a status code like 500 or ranges with a syntax like 500-599.

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.

query

The URL for the error page (hosted by service). You can use {status} in the query, that will be replaced by the received status code.