How to Set max_fails in Nginx Upstream Configuration

To set max_fails in an Nginx upstream block, add it as a parameter to each server line like server 192.168.1.1 max_fails=3;. This limits the number of failed attempts before Nginx marks the server as unavailable temporarily.

Syntax

The max_fails parameter is used inside an upstream block in the Nginx configuration. It defines how many failed attempts to connect to a server are allowed before Nginx stops sending requests to it for a period defined by fail_timeout.

Each server line can have max_fails and fail_timeout parameters:

• server address: IP or hostname of the backend server.
• max_fails=number: Maximum failed attempts before marking the server down.
• fail_timeout=time: Time period to consider failures and to keep the server down.

nginx

upstream backend {
    server 192.168.1.1 max_fails=3 fail_timeout=30s;
    server 192.168.1.2 max_fails=2 fail_timeout=20s;
}

Example

This example shows an upstream block with two backend servers. Each server has max_fails set to limit retries before marking it as down. The fail_timeout sets how long the server stays down after failures.

nginx

upstream backend {
    server 192.168.1.10 max_fails=3 fail_timeout=10s;
    server 192.168.1.11 max_fails=5 fail_timeout=15s;
}

server {
    listen 80;
    location / {
        proxy_pass http://backend;
    }
}

Output

Nginx will try each server up to the max_fails limit. If a server fails 3 times within 10 seconds, it will be temporarily marked down and skipped for 10 seconds.

Common Pitfalls

Common mistakes when setting max_fails include:

• Setting max_fails too low, causing servers to be marked down too quickly on minor issues.
• Not setting fail_timeout, which defaults to 10 seconds, possibly too short or too long for your use case.
• Assuming max_fails counts all errors; it only counts connection failures and timeouts, not HTTP errors.

Always test your settings to balance availability and fault tolerance.

nginx

upstream backend {
    # Wrong: max_fails too low
    server 192.168.1.1 max_fails=1 fail_timeout=30s;

    # Right: reasonable max_fails
    server 192.168.1.2 max_fails=3 fail_timeout=30s;
}

Quick Reference

Parameter	Description	Example
max_fails	Number of failed attempts before marking server down	max_fails=3
fail_timeout	Time window to count failures and duration to keep server down	fail_timeout=30s
server	Backend server address with optional parameters	server 192.168.1.1 max_fails=3 fail_timeout=30s

Key Takeaways

Set max_fails in the upstream server line to limit retries on failed connections.

Use fail_timeout to define how long a server stays marked down after failures.

max_fails counts connection failures, not HTTP error responses.

Avoid setting max_fails too low to prevent unnecessary server downtime.

Test your configuration to find the right balance for your environment.