How to Set fail_timeout in Nginx Upstream Configuration

To set fail_timeout in an Nginx upstream block, add it as a parameter to a server line like server 127.0.0.1:8080 fail_timeout=10s;. This sets how long a server is considered failed after consecutive errors before Nginx tries it again.

Syntax

The fail_timeout parameter is used inside an upstream block on a server directive. It controls the time period during which a server is marked as unavailable after it fails a number of consecutive attempts.

• server address: IP or hostname with port
• fail_timeout=duration: Time to consider server down after failures (e.g., 10s, 1m)

nginx

upstream backend {
    server 192.168.1.10:8080 fail_timeout=30s max_fails=3;
    server 192.168.1.11:8080 fail_timeout=10s max_fails=3;
}

Example

This example shows an upstream block with two backend servers. Each server has a fail_timeout set to control how long Nginx waits before retrying a failed server.

nginx

http {
    upstream backend {
        server 127.0.0.1:8080 fail_timeout=15s max_fails=3;
        server 127.0.0.1:8081 fail_timeout=30s max_fails=3;
    }

    server {
        listen 80;

        location / {
            proxy_pass http://backend;
        }
    }
}

Output

Nginx starts and routes requests to 127.0.0.1:8080 and 127.0.0.1:8081. If one server fails 1 or more times within the fail_timeout period, it is marked down and skipped for that duration.

Common Pitfalls

Common mistakes when setting fail_timeout include:

• Setting fail_timeout too low, causing servers to be marked down too quickly on transient errors.
• Not setting fail_timeout at all, which defaults to 10 seconds and may not suit your environment.
• Confusing fail_timeout with max_fails, which controls how many failures trigger marking the server down.

Always set fail_timeout together with max_fails for predictable failure handling.

nginx

upstream backend {
    # Wrong: no fail_timeout, default 10s may be too short
    server 127.0.0.1:8080 max_fails=3;

    # Right: set fail_timeout explicitly
    server 127.0.0.1:8081 max_fails=3 fail_timeout=30s;
}

Quick Reference

Directive	Description	Example
fail_timeout	Time to mark server down after failures	fail_timeout=20s
max_fails	Number of failed attempts before marking down	max_fails=3
server	Defines backend server with optional parameters	server 10.0.0.1:80 max_fails=2 fail_timeout=15s

Key Takeaways

Set fail_timeout inside the upstream server directive to control downtime after failures.

Use fail_timeout together with max_fails for effective failure detection.

Choose fail_timeout duration based on your server reliability and retry needs.

Not setting fail_timeout uses a default of 10 seconds, which may not fit all cases.

Proper fail_timeout settings improve load balancing and service availability.