traefik/docs/content/middlewares/http/errorpages.md

title	description
Traefik ErrorPage Documentation	In Traefik Proxy, the ErrorPage middleware returns custom pages according to configured ranges of HTTP Status codes. Read the technical documentation.

ErrorPage

It Has Never Been Easier to Say That Something Went Wrong {: .subtitle }

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

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

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-errorpage
spec:
  errors:
    status:
      - "500-599"
    query: /{status}.html
    service:
      name: whoami
      port: 80

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

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

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

# Custom Error Page for 5XX
http:
  middlewares:
    test-errorpage:
      errors:
        status:
          - "500-599"
        service: serviceError
        query: "/{status}.html"

  services:
    # ... definition of error-handler-service and my-service

# Custom Error Page for 5XX
[http.middlewares]
  [http.middlewares.test-errorpage.errors]
    status = ["500-599"]
    service = "serviceError"
    query = "/{status}.html"

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

!!! note ""

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 (500-599 will trigger with every code between 500 and 599, 500 and 599 included).

!!! note ""

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 (`500-599`),
or a combination of the two (`404,418,500-599`).

service

The service that will serve the new requested error page.

!!! note ""

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

!!! info "Host Header"

By default, the client `Host` header value is forwarded to the configured error [service](#service).
To forward the `Host` value corresponding to the configured error service URL, the [passHostHeader](../../../routing/services/#pass-host-header) option must be set to `false`.     

query

The URL for the error page (hosted by service). You can use the {status} variable in the query option in order to insert the status code in the URL.