Avi Vantage Custom Error Responses


On encountering an error that prevents it from processing an HTTP request or response, Avi Vantage returns a generic error message with a status code to the client. This article discusses customizing the error message page returned by Avi Vantage on encountering an error.

Note: This feature is supported starting in 17.2.12.

Note: A customized error response page is different from having Avi Vantage return a custom web page using a DataScript or policy, when the server returns the error page.


Avi Vantage generates error pages for the listed conditions:

  • A request is blocked due to a Web Application Firewall (WAF) policy match.
  • HTTP request or response parsing error, such as an invalid request.
  • Back-end server handshake failure or connection timeout.
  • Logic failure in a DataScript.

Pool Fail Action

In cases where all servers are down and the pool servers are unable to return a page, a pool may be configured to return a custom error page.

Navigate to Applications > Pools and click on the pool to be edited. In the Advanced tab, under Pool Failure Settings, set the Pool Fail Action to HTTP Local Response. Set the desired return code under Status Code and optionally upload the HTML file in the Upload File field.


By default, the pool fail action is set to Close Connection and a TCP reset is sent to the client. This action takes effect after an HTTP request is received and before the response. For instance, a WAF security violation triggered by a client request would take precedence. The WAF would send out a 403 error page rather than a page sent by the Pool Fail Action.


DataScripts can be used to return custom error messages to the client. For this, the DataScript needs to first detect the error.

A custom error page DataScript is triggered by the RESP_FAILED event, which occurs when Avi Vantage is unable to process a transaction and return a page to the client. Note that this event is only executed when Avi Vantage generates the error. If the error is generated by the server, as in the case of 503 (service unavailable) response, the DataScript should use the HTTP_RESP event to overwrite the page that is returned by the server. The avi.http.internal_status() function will return the reason for this error. This information is embedded within the returned custom error page. The response is then sent to the client by embedding the custom HTML into the avi.http.response() function. Alternatively, an HTTP redirect could be used via avi.http.redirect().


status = avi.http.internal_status()
html = "Your request could not be completed. Please contact support."

if status then html = html .. " Reason: " .. status end
html = html .. ""
avi.http.response(503, {content_type="text/html"}, html)

Error Page Profile

Starting with Avi Vantage release 17.2.12, you can configure one or more custom error pages on Avi Vantage.

Navigate to Templates > Error Page > Error Page Profile and click on Create.


These pages are simple HTML pages that are defined in the error page body. An error page profile can point to multiple error page bodies. Ensure that each error page profile is associated with a different HTTP status code or a range of status codes.

Custom tokens or variables are dynamic data generated by Avi Vantage that can be inserted into the returned page. These variables must be separated by a space, after and before. The Avi parser will reject other string ($) characters contained within the HTML of an error page. The following are the available variables:

  • $status – Returns the status code that Avi Vantage returns to the client.

  • $request_id – Returns an unique identifier that Avi Vantage assigns to the specific request or response. This identifier is also included in the logs. When this identifier is returned to the client, the specific transaction can be located in the logs to find the reason for the error. A common use case is that of WAF, which may block a client request for a wide range of violations. By locating the request ID in the logs, the administrator can validate if the blocked request or WAF signature should be exempted from blocking future requests.

  • $vs_name – Returns the name of the virtual service. This name could be different from the connected FQDN clients.


Style sheets, JavaScript, or even base64-encoded images can be embedded within a single HTML file as inline objects for robust error pages. Alternatively, the HTML page can include links to another site for retrieving these additional objects.