Max fails and fail timeout in Nginx - Step-by-Step Execution

Process Flow - Max fails and fail timeout

Start request to backend

↓

Request success?

↓

Reset fail count

↓

Fail count >= max_fails?

No→Continue sending requests

Yes↓

Mark backend as down

↓

Wait fail_timeout seconds

↓

Retry backend

↓

If success, mark backend up and reset fail count

↓

Repeat process

This flow shows how nginx tracks failed requests to a backend server, marks it down after max fails, waits fail_timeout seconds, then retries.

Execution Sample

Nginx

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

proxy_pass http://backend;

Configures nginx to mark backend1 down after 3 failed requests within 10 seconds fail timeout.

Process Table

Step	Request Number	Request Result	Fail Count	Backend Status	Action
1	1	Success	0	Up	Reset fail count to 0, send next request
2	2	Fail	1	Up	Increment fail count to 1, send next request
3	3	Fail	2	Up	Increment fail count to 2, send next request
4	4	Fail	3	Down	Increment fail count to 3, mark backend Down
5	5	Request blocked	3	Down	Do not send request, wait fail_timeout
6	6	Retry after timeout	3	Down	Retry backend after 10s timeout
7	7	Success	0	Up	Reset fail count, mark backend Up, continue requests

💡 Backend marked down after 3 fails; after 10s fail_timeout, backend retried and marked up on success.

Status Tracker

Variable	Start	After 1	After 2	After 3	After 4	After 5	After 6	Final
Fail Count	0	0	1	2	3	3	3	0
Backend Status	Up	Up	Up	Up	Down	Down	Down	Up

Key Moments - 3 Insights

Why does nginx stop sending requests after max_fails is reached?

Because once fail count reaches max_fails (row 4), nginx marks backend as Down and blocks further requests until fail_timeout passes (row 5).

What happens to fail count after a successful retry?

After a successful retry (row 7), nginx resets fail count to 0 and marks backend Up to resume normal requests.

Does fail_timeout start counting after the first failure or after max_fails?

fail_timeout countdown starts after max_fails is reached and backend is marked Down (row 4 to 5).

Visual Quiz - 3 Questions

Look at the execution table, what is the fail count at request number 3?

A 1

B 2

C 3

D 0

💡 Hint

Check the Fail Count column at Step 3 in the execution_table.

At which request number does nginx mark the backend as Down?

A Request 2

B Request 3

C Request 4

D Request 5

💡 Hint

Look at Backend Status and Action columns in execution_table rows.

If fail_timeout was increased to 20s, how would the execution table change?

A The backend would be retried after 20s instead of 10s at step 6

B Fail count would reset earlier

C Backend would never be marked Down

D Fail count would increment faster

💡 Hint

Refer to the Action column at Step 6 about retry timing.

Concept Snapshot

nginx max_fails and fail_timeout:
- max_fails: number of failed requests before marking backend down
- fail_timeout: time to wait before retrying backend
- After max_fails fails, backend marked Down
- Requests blocked during fail_timeout
- After timeout, backend retried and marked Up on success

Full Transcript

This visual execution trace shows how nginx uses max_fails and fail_timeout to manage backend server health. Each request increments fail count on failure. When fail count reaches max_fails, nginx marks the backend as down and stops sending requests. It waits fail_timeout seconds before retrying. If retry succeeds, fail count resets and backend is marked up again. This prevents sending requests to failing servers and improves reliability.

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