Service reliability

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 ultimate number of times the load balancer will try to reconnect:

  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

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

Available since

  • HAProxy 2.0
  • HAProxy Enterprise 2.0r1
  • HAProxy ALOHA 11.5

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

Do you have any suggestions on how we can improve the content of this page?