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.

Practice

1. What does the max_fails directive control in an nginx upstream server block?

easy

A. The number of failed attempts before marking the server as down

B. The total number of requests allowed to the server

C. The timeout duration for each request

D. The maximum number of servers in the upstream block

Solution

1. Step 1: Understand the role of max_fails

   The max_fails directive sets how many failed connection attempts to a server are allowed before nginx marks it as down.

2. Step 2: Differentiate from other directives

   It does not limit total requests or set timeouts; it only counts failures.

3. Final Answer:

   The number of failed attempts before marking the server as down -> Option A

4. Quick Check:

   max_fails = failure count limit [OK]

Hint: max_fails counts failures before marking server down [OK]

Common Mistakes:

• Confusing max_fails with request limits
• Thinking max_fails sets timeout duration
• Assuming max_fails controls total servers

2. Which of the following is the correct syntax to set max_fails to 3 and fail_timeout to 30s for a server in nginx?

easy

A. server 192.168.1.1 max_fails 3 fail_timeout 30s;

B. server 192.168.1.1 max_fails=3 fail_timeout=30s;

C. server 192.168.1.1 max_fails:3 fail_timeout:30s;

D. server 192.168.1.1 max_fails(3) fail_timeout(30s);

Solution

1. Step 1: Recall nginx directive syntax

   nginx uses space-separated key value pairs without equal signs inside server blocks.

2. Step 2: Match correct syntax

   server 192.168.1.1 max_fails 3 fail_timeout 30s; uses correct syntax: max_fails 3 fail_timeout 30s; with spaces and semicolon.

3. Final Answer:

   server 192.168.1.1 max_fails 3 fail_timeout 30s; -> Option A

4. Quick Check:

   nginx directives use space-separated key value pairs [OK]

Hint: Use space-separated key value pairs for nginx server parameters [OK]

Common Mistakes:

• Using equal signs (=) in nginx directives
• Using colons (:) instead of spaces
• Adding parentheses around values

3. Given this nginx upstream configuration:

upstream backend {
    server 192.168.0.1 max_fails=2 fail_timeout=10s;
    server 192.168.0.2 max_fails=3 fail_timeout=20s;
}

What happens if 192.168.0.1 fails 3 times within 10 seconds?

medium

A. 192.168.0.2 is marked down instead

B. 192.168.0.1 is marked down for 20 seconds

C. 192.168.0.1 is marked down for 10 seconds

D. 192.168.0.1 is never marked down

Solution

1. Step 1: Understand max_fails and fail_timeout for 192.168.0.1

   max_fails=2 means after 2 failures, server is marked down. fail_timeout=10s means it stays down for 10 seconds.

2. Step 2: Analyze 3 failures within 10 seconds

   3 failures exceed max_fails, so server is marked down for fail_timeout duration (10 seconds).

3. Final Answer:

   192.168.0.1 is marked down for 10 seconds -> Option C

4. Quick Check:

   Failures > max_fails triggers down for fail_timeout [OK]

Hint: Failures over max_fails trigger down for fail_timeout [OK]

Common Mistakes:

• Confusing fail_timeout values between servers
• Assuming server stays down indefinitely
• Marking wrong server down

4. You set max_fails 3 fail_timeout 30s; for a server, but nginx never marks it down even after many failures. What is the likely mistake?

medium

A. Setting fail_timeout to 0

B. Using incorrect syntax like max_fails 3

C. Not enabling proxy_next_upstream directive

D. Using max_fails outside the upstream block

Solution

1. Step 1: Check location of max_fails directive

   max_fails must be inside the upstream block; placing it outside means nginx ignores it.

2. Step 2: Understand effect of incorrect placement

   Incorrect placement means nginx does not apply the max_fails setting, so server is never marked down.

3. Final Answer:

   Using max_fails outside the upstream block -> Option D

4. Quick Check:

   Directive placement affects behavior [OK]

Hint: Ensure max_fails is inside upstream block [OK]

Common Mistakes:

• Using incorrect syntax like max_fails 3
• Assuming fail_timeout 0 disables marking down
• Ignoring proxy_next_upstream role

5. You want to configure nginx so that a backend server is marked down after 5 failures and stays down for 1 minute. Which configuration snippet achieves this correctly?

hard

A. server 10.0.0.1 max_fails=5 fail_timeout=60s;

B. server 10.0.0.1 max_fails 5 fail_timeout 1m;

C. server 10.0.0.1 max_fails=5 fail_timeout=60;

D. server 10.0.0.1 max_fails 5 fail_timeout 60;

Solution

1. Step 1: Confirm correct syntax for max_fails and fail_timeout

   nginx requires space-separated key value pairs without equal signs and time units for fail_timeout, e.g., 60s or 1m for 60 seconds.

2. Step 2: Evaluate options for correctness

   server 10.0.0.1 max_fails 5 fail_timeout 1m; uses correct syntax with spaces and time unit. A uses equals signs which is invalid. C missing time unit 's'. D missing equals and time unit.

3. Final Answer:

   server 10.0.0.1 max_fails 5 fail_timeout 1m; -> Option B

4. Quick Check:

   Use space-separated key value pairs and time units in directives [OK]

Hint: Use space-separated key value pairs, time units like 60s or 1m [OK]

Common Mistakes:

• Omitting time units for fail_timeout
• Using invalid time formats
• Using equals signs in directives