502 Bad Gateway troubleshooting in Nginx - Mini Project: Build & Apply

502 Bad Gateway Troubleshooting with Nginx

📖 Scenario: You are managing a web server using Nginx. Sometimes, users see a 502 Bad Gateway error when trying to access your website. This error means Nginx cannot get a proper response from the backend server.In this project, you will learn how to check the Nginx configuration and backend server status to find and fix the cause of the 502 error.

🎯 Goal: Build a simple troubleshooting process to identify and fix a 502 Bad Gateway error in Nginx by checking configuration and backend server status.

📋 What You'll Learn

Create a variable with the backend server address

Add a variable for the backend server port

Write a command to check if the backend server is running

Write a command to display the Nginx error log for 502 errors

💡 Why This Matters

🌍 Real World

Web servers often use Nginx as a gateway to backend services. When backend services fail or are unreachable, users see 502 errors. Troubleshooting these errors quickly restores website availability.

💼 Career

DevOps engineers and system administrators must know how to diagnose and fix 502 Bad Gateway errors to keep web applications running smoothly.

1

Setup backend server address variable

Create a variable called backend_server and set it to the string "127.0.0.1" which is the IP address of the backend server.

Nginx

# Create a variable called backend_server with value "127.0.0.1"
# Your code here

Hint

Use a simple assignment like backend_server = "127.0.0.1".

2

Add backend server port variable

Add a variable called backend_port and set it to the integer 8080, which is the port number where the backend server listens.

Nginx

backend_server = "127.0.0.1"
# Create a variable called backend_port with value 8080
# Your code here

Hint

Use backend_port = 8080 to set the port number.

3

Check backend server status

Write a command string called check_command that uses curl to check if the backend server is running at backend_server and backend_port. The command should be: curl -s --connect-timeout 2 http://127.0.0.1:8080 using the variables.

Nginx

backend_server = "127.0.0.1"
backend_port = 8080
# Create a variable check_command to check backend server with curl
# Your code here

Hint

Use an f-string to build the curl command with variables.

4

Display Nginx error log for 502 errors

Write a command string called log_command that uses grep to find lines containing 502 in the Nginx error log file located at /var/log/nginx/error.log. The command should be: grep 502 /var/log/nginx/error.log.

Nginx

backend_server = "127.0.0.1"
backend_port = 8080
check_command = f"curl -s --connect-timeout 2 http://{backend_server}:{backend_port}"
# Create a variable log_command to grep 502 errors from Nginx error log
# Your code here

Hint

Use log_command = "grep 502 /var/log/nginx/error.log" to find 502 errors.

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