Error pages

Available since

HAProxy 2.2
HAProxy Enterprise 2.2r1
HAProxy ALOHA 12.5

You can customize the HTTP error pages clients receive to add your own styling, text, and images. Two scenarios exist:

Customize HTTP errors generated by the load balancer
Customize HTTP errors received from the backend web servers

Customize load balancer errors Jump to heading

The http-errors section locates custom HTML pages to return to clients when errors occur. By default, the load balancer will serve these pages only if it initiated the error itself. For example, it will return the page for a 503 Service Unavailable error if it can’t reach any backend servers.

To define custom error pages:

Create a file with a .http file extension and add HTTP metadata at the top of the file. The metadata should include the HTTP start line and headers. In the following example, we define a custom 403 error page, and save it as 403.http:

403.http
html
HTTP/1.1 403 Forbidden
Cache-Control: no-cache
Connection: close
Content-Type: text/html
<!DOCTYPE html>
<html>
   <body>
      <h1>403 Forbidden</h1>
      <p>Sorry, but you are not authorized to view this page.</p>
   </body>
</html>

403.http
html
HTTP/1.1 403 Forbidden
Cache-Control: no-cache
Connection: close
Content-Type: text/html
<!DOCTYPE html>
<html>
   <body>
      <h1>403 Forbidden</h1>
      <p>Sorry, but you are not authorized to view this page.</p>
   </body>
</html>

In your load balancer configuration, add an http-errors section with one or more errorfile directives, where each specifies an HTTP response status code and the path to an error file. In the following example, we define one custom error page to use for 403 Forbidden errors:
```
haproxy
http-errors myerrors
  errorfile 403 /403.http
```
```
haproxy
http-errors myerrors
  errorfile 403 /403.http
```
You can define different error page files for different response status code:
```
haproxy
http-errors myerrors
  errorfile 403 /403.http
  errorfile 404 /404.http
  errorfile 500 /500.http
```
```
haproxy
http-errors myerrors
  errorfile 403 /403.http
  errorfile 404 /404.http
  errorfile 500 /500.http
```

To use custom error pages, reference the name of the http-errors section by using an errorfiles directive in your frontend:

haproxy
frontend www
  bind :80
  default_backend webservers
  errorfiles myerrors

haproxy
frontend www
  bind :80
  default_backend webservers
  errorfiles myerrors

Customize web server errors Jump to heading

You can intercept error responses from backend web servers and replace them with your custom error pages.

In your load balancer configuration, add an http-errors section with one or more errorfile directives, where each specifies an HTTP response status code and the path to an error file. In the following example, we define one custom error page to use for 404 Not Found errors:
```
haproxy
http-errors myerrors
  errorfile 404 /404.http
```
```
haproxy
http-errors myerrors
  errorfile 404 /404.http
```

In your frontend, add an errorfiles directive that refers to your http-errors section. Also, add an http-response return directive to intercept any response from the server that has a 404 status. It then, by specifying default-errorfiles, returns the 404 errorfile that was defined in the myerrors section:

haproxy
frontend www
  bind :80
  default_backend webservers
  errorfiles myerrors
  http-response return  status 404  default-errorfiles  if { status 404 }

haproxy
frontend www
  bind :80
  default_backend webservers
  errorfiles myerrors
  http-response return  status 404  default-errorfiles  if { status 404 }

Optional: The default-errorfiles argument instructs the load balancer to use the error files specified by the errorfiles directive within the frontend. Alternatively, you can indicate a different set of error files to use by setting the errorfiles argument on the http-response return line. In the following example, we use the 404 page from the alternative_errors if the status is 404 and the Host header is example.com:

haproxy
http-errors myerrors
  errorfile 403 /403.http
  errorfile 404 /404.http
  errorfile 500 /500.http
http-errors alternative_errors
  errorfile 403 /403-alt.http
  errorfile 404 /404-alt.http
  errorfile 500 /500-alt.http
frontend www
  bind :80
  default_backend webservers
  http-request set-var(txn.host) req.hdr(host)
  errorfiles myerrors
  http-response return  status 404  errorfiles alternative_myerrors  if { status 404 } { var(txn.host) example.com }
  http-response return  status 404  default-errorfiles  if { status 404 } !{ var(txn.host) example.com }

haproxy
http-errors myerrors
  errorfile 403 /403.http
  errorfile 404 /404.http
  errorfile 500 /500.http
http-errors alternative_errors
  errorfile 403 /403-alt.http
  errorfile 404 /404-alt.http
  errorfile 500 /500-alt.http
frontend www
  bind :80
  default_backend webservers
  http-request set-var(txn.host) req.hdr(host)
  errorfiles myerrors
  http-response return  status 404  errorfiles alternative_myerrors  if { status 404 } { var(txn.host) example.com }
  http-response return  status 404  default-errorfiles  if { status 404 } !{ var(txn.host) example.com }

Product Documentation

API Documentation

Configuration Documentation

Error pages

Customize load balancer errors Jump to heading

Customize web server errors Jump to heading

See also Jump to heading

Product Documentation

API Documentation

Configuration Documentation

Customize load balancer errors Jump to heading #

Customize web server errors Jump to heading #

See also Jump to heading #

Privacy Settings

Customize load balancer errors Jump to heading

Customize web server errors Jump to heading

See also Jump to heading