502 Bad Gateway troubleshooting in Nginx - Step-by-Step Execution

Process Flow - 502 Bad Gateway troubleshooting

Client sends request

↓

Nginx receives request

↓

Nginx forwards to backend server

↓

Backend server processes request

↓

Backend server responds

↓

Nginx receives response

↓

Nginx sends response to client

↓

Nginx returns 502 Bad Gateway error

This flow shows how Nginx acts as a middleman between client and backend server, and returns 502 error if backend fails.

Execution Sample

Nginx

curl -I http://example.com
# Nginx tries to get response from backend
# Backend is down or unreachable
# Nginx returns 502 Bad Gateway

This simulates a client request to Nginx which fails to get a valid response from backend, causing 502 error.

Process Table

Step	Action	Nginx Status	Backend Status	Result
1	Client sends HTTP request	Waiting	Idle	Request received by Nginx
2	Nginx forwards request to backend	Waiting for backend	Processing request	Request sent to backend
3	Backend server fails to respond (down or timeout)	Timeout waiting	No response	No response received
4	Nginx detects backend failure	Error detected	No response	Prepares 502 Bad Gateway
5	Nginx sends 502 Bad Gateway to client	Responded with 502	No response	Client receives 502 error

💡 Backend server failure or timeout causes Nginx to return 502 Bad Gateway error

Status Tracker

Variable	Start	After Step 2	After Step 3	After Step 4	Final
Nginx Status	Idle	Waiting for backend	Timeout waiting	Error detected	Responded with 502
Backend Status	Idle	Processing request	No response	No response	No response
Client Response	None	None	None	None	502 Bad Gateway

Key Moments - 3 Insights

Why does Nginx return 502 instead of forwarding backend errors?

Nginx returns 502 when it cannot get any valid response from backend, not when backend returns an error. See execution_table step 3 and 4 where backend fails to respond.

Can a misconfigured Nginx cause 502 errors?

Yes, if Nginx points to wrong backend address or port, it cannot connect and returns 502. This is shown in step 3 where backend is unreachable.

Does a 502 error mean Nginx itself is down?

No, Nginx is working but backend is failing or unreachable. execution_table step 1 and 5 show Nginx receives request and sends 502 response.

Visual Quiz - 3 Questions

Look at the execution table, what is Nginx status at step 3?

A Waiting for backend

B Error detected

C Timeout waiting

D Responded with 502

💡 Hint

Check the 'Nginx Status' column at step 3 in the execution_table.

At which step does Nginx send the 502 Bad Gateway response to the client?

A Step 5

B Step 3

C Step 4

D Step 2

💡 Hint

Look for the step where 'Client Response' changes to '502 Bad Gateway' in variable_tracker.

If the backend server was healthy and responded normally, how would the 'Backend Status' change at step 3?

A No response

B Responded successfully

C Processing request

D Idle

💡 Hint

Consider what a normal backend response means compared to the failure shown in execution_table step 3.

Concept Snapshot

502 Bad Gateway means Nginx can't get a valid response from backend.
Nginx forwards client requests to backend server.
If backend is down or unreachable, Nginx returns 502 error.
Check backend server status and Nginx config for troubleshooting.
Use logs and curl to test backend connectivity.

Full Transcript

When a client sends a request, Nginx forwards it to the backend server. If the backend server is down or does not respond, Nginx waits but eventually times out. At this point, Nginx detects the failure and returns a 502 Bad Gateway error to the client. This error means Nginx is working but cannot get a valid response from the backend. Troubleshooting involves checking backend server health, network connectivity, and Nginx configuration. Logs and simple curl commands help verify backend availability.

Practice

1. What does a 502 Bad Gateway error usually indicate in nginx?

easy

A. nginx cannot get a valid response from the backend server

B. nginx configuration file has a syntax error

C. nginx server is overloaded with too many requests

D. nginx is running out of disk space

Solution

1. Step 1: Understand the meaning of 502 Bad Gateway

   A 502 error means the gateway (nginx) got an invalid response from the backend server it tries to connect to.

2. Step 2: Identify the cause related to backend communication

   This error is not about nginx config syntax or server load, but about backend response failure.

3. Final Answer:

   nginx cannot get a valid response from the backend server -> Option A

4. Quick Check:

   502 Bad Gateway = backend response failure [OK]

Hint: 502 means backend server response problem [OK]

Common Mistakes:

• Confusing 502 with nginx config syntax errors
• Thinking 502 means nginx is overloaded
• Assuming 502 is due to disk space issues

2. Which of the following nginx configuration directives is essential to correctly proxy requests to a backend server to avoid 502 errors?

easy

A. listen 8080;

B. root /var/www/html;

C. server_name localhost;

D. proxy_pass http://backend_server;

Solution

1. Step 1: Identify the directive that defines backend server address

   The proxy_pass directive tells nginx where to send requests, crucial for proxying.

2. Step 2: Understand other directives' roles

   listen sets port, server_name sets hostname, root sets static file location; none define backend proxy.

3. Final Answer:

   proxy_pass http://backend_server; -> Option D

4. Quick Check:

   proxy_pass sets backend URL [OK]

Hint: proxy_pass sets backend URL to avoid 502 [OK]

Common Mistakes:

• Using listen instead of proxy_pass for backend
• Confusing server_name with backend address
• Setting root instead of proxy_pass for proxying

3. Given this nginx error log snippet:
connect() failed (111: Connection refused) while connecting to upstream
What is the most likely cause of the 502 error?

medium

A. nginx has insufficient permissions to read files

B. nginx configuration syntax error

C. Backend server is not running or not accepting connections

D. DNS resolution failure for backend server

Solution

1. Step 1: Interpret the error message

   "Connection refused" means nginx tried to connect but backend server refused, likely because it is down or not listening.

2. Step 2: Rule out other causes

   Syntax errors cause config reload failures, permissions affect file access, DNS failure shows different errors.

3. Final Answer:

   Backend server is not running or not accepting connections -> Option C

4. Quick Check:

   Connection refused = backend down [OK]

Hint: Connection refused means backend server is down [OK]

Common Mistakes:

• Assuming syntax error from connection refused
• Blaming nginx file permissions
• Thinking DNS failure causes connection refused

4. You see a 502 error in nginx logs caused by upstream timed out. Which fix is most appropriate?

medium

A. Clear browser cache and cookies

B. Increase proxy_read_timeout in nginx config

C. Change server_name directive

D. Restart nginx service immediately

Solution

1. Step 1: Understand the timeout error

   "upstream timed out" means nginx waited too long for backend response.

2. Step 2: Adjust nginx timeout settings

   Increasing proxy_read_timeout lets nginx wait longer before giving 502 error.

3. Final Answer:

   Increase proxy_read_timeout in nginx config -> Option B

4. Quick Check:

   Timeout error fixed by increasing proxy_read_timeout [OK]

Hint: Increase proxy_read_timeout to fix upstream timeout [OK]

Common Mistakes:

• Restarting nginx without config change
• Changing server_name unrelated to timeout
• Clearing browser cache won't fix backend timeout

5. You fixed a backend server crash causing 502 errors. What is the correct next step to apply nginx changes and confirm the fix?

hard

A. Reload or restart nginx and check error logs for 502 errors

B. Clear browser cache and refresh the page

C. Edit nginx config to change server_name

D. Delete nginx access logs to free space

Solution

1. Step 1: Apply nginx configuration and backend fixes

   After fixing backend, reload or restart nginx to apply any config changes and reset connections.

2. Step 2: Verify fix by checking logs

   Check nginx error logs to confirm 502 errors no longer appear, ensuring the problem is solved.

3. Final Answer:

   Reload or restart nginx and check error logs for 502 errors -> Option A

4. Quick Check:

   Reload nginx and check logs to confirm fix [OK]

Hint: Reload nginx and check logs after backend fix [OK]

Common Mistakes:

• Only clearing browser cache without server reload
• Changing unrelated config like server_name
• Deleting logs instead of reading them