Retries and redispatches

The retry and redispatch options attempt to reconnect after a failed connection or resend after a failed HTTP request, which can protect against the following faults:

• network connectivity issues (including SSL handshake errors and unexpected server failures)
• HTTP errors
• servers taking too long to respond

First, consider the behavior of health checks, which monitor each backend server’s connectivity and remove problematic servers from the load balancing rotation. After removing a server from load balancing, the flow of traffic is stopped to that server, which is preferable when the connectivity problem is likely to be long-lasting.

Nevertheless, not all connection problems are long lasting and retrying the connection immediately could successfully overcome short-term connection problems. Connection retries are enabled by default, but you can change their behavior.

Set the number of retries Jump to heading #

By default, the load balancer will retry a failed connection 3 times. To change the number of times the load balancer will try to reconnect, set the retries directive to a different value.

1. In a defaults or backend section, add a retries directive and set its value to the number of times to retry a failed connection attempt.

   Below, we attempt to connect to the server 4 times before giving up and returning a Service Unavailable error to the client:

   haproxy
   backend webservers
     mode http
     balance roundrobin
     server s1 192.168.1.25:80 check
     server s2 192.168.1.26:80 check
     retries 4

   haproxy
   backend webservers
     mode http
     balance roundrobin
     server s1 192.168.1.25:80 check
     server s2 192.168.1.26:80 check
     retries 4

2. Optional: Add the timeout connect directive to set the delay between retries.

   Below, the server performs the next retry after 3 seconds, optimistically giving the server time to overcome from short-term connectivity issues.

   haproxy
   backend webservers
     mode http
     balance roundrobin
     server s1 192.168.1.25:80 check
     server s2 192.168.1.26:80 check
     retries 4
     timeout connect 3s

   haproxy
   backend webservers
     mode http
     balance roundrobin
     server s1 192.168.1.25:80 check
     server s2 192.168.1.26:80 check
     retries 4
     timeout connect 3s

Change the value with set-retries Jump to heading #

Use tcp-request content set-retries if using mode tcp or http-request set-retries if using mode http to change the value of the retries directive dynamically. Assign an interger between 0 and 100. For example, suppose that all servers except for one have become unreachable. In that case, you might make more connection attempts to the server that you have left.

Below, we use nbsrv to check the number of servers that are currently up in the webservers backend. If it’s only one, we use http-request set-retries to change the retries value to 10.

haproxy
backend webservers
  mode http
  balance roundrobin
  retry-on all-retryable-errors
  # Default retries value
  retries 3
  # Dynamically change retries value if only one server is up
  http-request set-retries 10 if { nbsrv(webservers) 1 }
  # list of servers
  server web1 172.16.0.10:80 check maxconn 30
  server web2 172.16.0.11:80 check maxconn 30
  server web3 172.16.0.12:80 check maxconn 30

haproxy
backend webservers
  mode http
  balance roundrobin
  retry-on all-retryable-errors
  # Default retries value
  retries 3
  # Dynamically change retries value if only one server is up
  http-request set-retries 10 if { nbsrv(webservers) 1 }
  # list of servers
  server web1 172.16.0.10:80 check maxconn 30
  server web2 172.16.0.11:80 check maxconn 30
  server web3 172.16.0.12:80 check maxconn 30

Redispatch to a different server Jump to heading #

Instead of trying to reconnect to the same server, you can configure option redispatch to try with a different server in the backend.

1. Add the option redispatch directive to retry with a different server:

   haproxy
   backend webservers
     mode http
     balance roundrobin
     server s1 192.168.1.25:80 check
     server s2 192.168.1.26:80 check
     retries 4
     option redispatch

   haproxy
   backend webservers
     mode http
     balance roundrobin
     server s1 192.168.1.25:80 check
     server s2 192.168.1.26:80 check
     retries 4
     option redispatch

2. Optional: Add a number of times to retry with the same server before redispatching to a different server. Below, we dispatch the request to another server after 2 failed retries:

   haproxy
   backend webservers
     mode http
     balance roundrobin
     server s1 192.168.1.25:80 check
     server s2 192.168.1.26:80 check
     retries 4
     option redispatch 2

   haproxy
   backend webservers
     mode http
     balance roundrobin
     server s1 192.168.1.25:80 check
     server s2 192.168.1.26:80 check
     retries 4
     option redispatch 2

Set when to retry Jump to heading #

Beyond retrying after a failed connection, you can also enable other conditions that should trigger a retry. Use the retry-on directive to specify the conditions.

1. Add the retry-on directive to define types of HTTP response codes that should trigger a retry. Below, we retry when the request fails due to failure 503 Service Unavailable or 504 Gateway Timeout:

   haproxy
   backend webservers
     mode http
     balance roundrobin
     server s1 192.168.1.25:80 check
     server s2 192.168.1.26:80 check
     retries 4
     retry-on 503 504

   haproxy
   backend webservers
     mode http
     balance roundrobin
     server s1 192.168.1.25:80 check
     server s2 192.168.1.26:80 check
     retries 4
     retry-on 503 504

   Options for the codes are:

   • 404
   • 408
   • 425
   • 500
   • 501
   • 502
   • 503
   • 504

   If you set retry-on, the default behavior of retrying failed TCP connections is not enabled unless you set retry-on to all-retryable-errors or a specific connection failure condition, such as conn-failure.

2. Optional: Add to the retry-on directive specific types of TCP connection problems that should also trigger a retry, in addition to HTTP response codes. Options include:

   • conn-failure
   • empty-response
   • junk-response
   • response-timeout
   • 0rtt-rejected
   • all-retryable-errors

   Below, we retry the connection if the connection could not be established or was closed while sending the request, in addition to when receiving a 503 response:

   haproxy
   backend webservers
     retry-on conn-failure empty-response 503

   haproxy
   backend webservers
     retry-on conn-failure empty-response 503

See also Jump to heading #

• option redispatch
• retries
• retry-on
• timeout connect