Max fails and fail timeout in Nginx - Commands & Configuration

Introduction

When a server or service is temporarily unreachable, nginx can stop trying to send requests to it after a certain number of failures or a timeout. This helps keep your website fast and reliable by avoiding slow or broken servers.

When you have multiple backend servers and want nginx to stop sending requests to a server that is failing repeatedly.

When you want to improve user experience by quickly switching to healthy servers without waiting too long for a slow server to respond.

When you want to avoid wasting resources retrying a server that is down or unreachable.

When you want to control how long nginx waits before trying a failed server again.

When you want to balance load but exclude servers that are temporarily unhealthy.

Config File - nginx.conf

nginx.conf

http {
    upstream backend {
        server backend1.example.com max_fails=3 fail_timeout=10s;
        server backend2.example.com max_fails=3 fail_timeout=10s;
    }

    server {
        listen 80;

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

This configuration defines an upstream group named backend with two servers.

The max_fails=3 means nginx will mark a server as failed after 3 unsuccessful attempts within the fail_timeout period.

The fail_timeout=10s means nginx will consider the server down for 10 seconds before trying it again.

The server block listens on port 80 and proxies requests to the backend group.

Commands

This command tests the nginx configuration file for syntax errors before applying it.

Terminal

nginx -t

Expected Output

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

This command reloads nginx to apply the new configuration without stopping the service.

Terminal

systemctl reload nginx

Expected Output

No output (command runs silently)

This command sends a simple request to nginx to check if it is proxying requests correctly after the configuration change.

Terminal

curl -I http://localhost

Expected Output

HTTP/1.1 200 OK

Server: nginx

Date: Thu, 01 Jan 1970 00:00:00 GMT

Content-Type: text/html

Content-Length: 612

Connection: keep-alive

Key Concept

If you remember nothing else from this pattern, remember: max_fails and fail_timeout help nginx avoid sending requests to servers that are temporarily down or slow.

Common Mistakes

Setting max_fails too high or fail_timeout too long

This causes nginx to keep trying a failing server too many times or for too long, slowing down user requests.

Set max_fails to a low number like 3 and fail_timeout to a short duration like 10 seconds to quickly skip bad servers.

Not reloading nginx after changing the config

Changes won't take effect until nginx reloads, so the old behavior continues.

Always run 'nginx -t' to check config, then 'systemctl reload nginx' to apply changes.

Summary

Configure max_fails and fail_timeout in the upstream server block to control failure handling.

Test the nginx configuration with 'nginx -t' before reloading.

Reload nginx to apply changes without downtime.

Use curl or similar tools to verify nginx is proxying requests correctly.