When Nginx is a reverse proxy server, 502 (Bad Gateway) and 504 (Gateway Timeout) errors are two common types of problems, corresponding to different failure scenarios. The following is a detailed analysis from error definitions, common causes to troubleshooting steps.
1. 502 Bad Gateway Error Analysis
1. Error definition
Meaning: When Nginx is used as a proxy server, an invalid response is received from the upstream server (such as PHP-FPM, Tomcat)
HTTP status code: 502 (Bad Gateway)
2. Common reasons
| Cause classification | Specific scenarios |
|---|---|
| Upstream server failure | - Application crash - Service not started - Service process exhausted (such as PHP-FPM process pool full) |
| Network connection issues | - Nginx does not work with upstream server network - Firewall blocks connection - Timeout setting is too short |
| Exhausted resources | - System file descriptor limitation - Service crashes due to insufficient memory |
| Configuration error | - Upstream server address configuration error - proxy_pass parameter setting error |
3. Troubleshooting steps
Step 1: Verify the upstream server status
# Check whether the service is runningsystemctl status php-fpm # Take PHP-FPM as an example # Try to access the upstream service directlycurl http://127.0.0.1:9000 # PHP-FPM default port
Step 2: Check Nginx Configuration
# Key configuration check exampleupstream backend {
server 192.168.1.100:8080; # Confirm whether the IP and port are correct}
server {
location / {
proxy_pass http://backend; # Confirm the protocol and path proxy_set_header Host $host;
}
}
Step 3: View Nginx Error Log
# Usually located in /var/log/nginx/tail -f /var/log/nginx/
Examples of common error messages:
- connect() failed (111: Connection refused): The upstream service has not started
- no live upstreams while connecting to upstream: The upstream server list is empty
- upstream timed out (110: Connection timed out): Connection timed out
Step 4: Check system resources
# Check memory usagefree -h # Check CPU usagetop # Check file descriptor restrictionsulimit -n
2. 504 Gateway Timeout Error Analysis
1. Error definition
Meaning: When Nginx is used as a proxy server, the upstream server fails to respond to the request within the specified time
HTTP status code: 504 (Gateway Timeout)
2. Common reasons
| Cause classification | Specific scenarios |
|---|---|
| Upstream services are slow to respond | - Database query takes too long - Complex computing tasks - Application deadlock |
| Network delay or congestion | -Nginx and upstream server network latency high - Insufficient bandwidth |
| The timeout parameter configuration is unreasonable | - proxy_connect_timeout setting is too short - proxy_read_timeout setting is too short |
3. Troubleshooting steps
Step 1: Verify upstream service performance
# Use curl to test the upstream service response timetime curl -I http://127.0.0.1:8080 # Replace with the actual game address
If the response time exceeds the default timeout (usually 60 seconds), the application needs to be optimized.
Step 2: Check the Nginx timeout configuration
# Key timeout parameters examplelocation / {
proxy_connect_timeout 60s; # Connection timeout proxy_send_timeout 60s; #Send request timeout proxy_read_timeout 120s; # Read response timeout proxy_buffer_size 16k;
proxy_buffers 4 32k;
}
Step 3: Monitor network status
# Check for network delaysping 192.168.1.100 # Upstream server IP # Check network bandwidth usageiftop -i eth0
Step 4: Analyze application performance
PHP application: Check slow query logs or Xdebug analysis
Java application: Use JProfiler or VisualVM to analyze thread state
Database: Optimize slow queries, add indexes
3. Comprehensive optimization suggestions
1. Adjust Nginx configuration parameters
# Optimize proxy configurationhttp {
proxy_connect_timeout 30s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
proxy_buffer_size 32k;
proxy_buffers 4 32k;
proxy_busy_buffers_size 64k;
proxy_temp_file_write_size 64k;
proxy_next_upstream error timeout invalid_header http_500 http_502 http_503 http_504;
}
2. Add upstream server resources
Increase the number of PHP-FPM worker processes:
# /etc// pm.max_children = 50 pm.start_servers = 10 pm.min_spare_servers = 5 pm.max_spare_servers = 20
3. Implement load balancing
upstream backend {
least_conn; # Minimum connection algorithm server weight=5;
server weight=5;
server backup; # Backup server}
4. Configure health checks
upstream backend {
server ;
server ;
check interval=3000 rise=2 fall=5 timeout=1000 type=http;
check_http_send "HEAD /health HTTP/1.0\r\n\r\n";
check_http_expect_alive http_2xx http_3xx;
}
4. Common misunderstandings and precautions
1) Obfuscation 502 and 504 errors:
- 502: The upstream returns an invalid response
- 504 is the upstream response timeout
2) Over-adjust the timeout parameters:
- Too long timeout will cause the client to wait for a long time
- It is recommended to set it reasonably in combination with application performance testing
3) Ignore system resource monitoring:
- Frequent 502/504 errors may be a signal that the system resources are exhausted
- It is recommended to configure Prometheus+Grafana for real-time monitoring
5. Quick diagnostic script
Here is a simple Bash script for quickly diagnosing Nginx 502/504 errors:
#!/bin/bash
# Nginx 502/504 Error Quick Diagnosis Script
# Color definitionRED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[0;33m'
NC='\033[0m' # No Color
echo -e "${YELLOW}=== Nginx 502/504Error Diagnostic Tool ===${NC}"
# Check Nginx service statusecho -e "\n${YELLOW}[1/5] examineNginxService status:${NC}"
if systemctl is-active --quiet nginx; then
echo -e "${GREEN}✓ NginxThe service is running${NC}"
else
echo -e "${RED}✗ NginxThe service is not running${NC}"
systemctl status nginx --no-pager
fi
# Check Nginx configurationecho -e "\n${YELLOW}[2/5] examineNginxConfiguration Syntax:${NC}"
nginx -t
NGINX_CONFIG_STATUS=$?
# Check upstream server connectivityecho -e "\n${YELLOW}[3/5] examine上游服务器连通性:${NC}"
UPSTREAM=$(grep -r "proxy_pass" /etc/nginx/ | awk -F'[ ;]' '{print $3}' | sort -u)
for server in $UPSTREAM; do
echo -e "\nTest the upstream server: ${server}"
IP=$(echo $server | cut -d':' -f1)
PORT=$(echo $server | cut -d':' -f2)
if ping -c 1 $IP &>/dev/null; then
echo -e "${GREEN}✓ ${IP} Internet accessible${NC}"
else
echo -e "${RED}✗ ${IP} Unreachable Internet${NC}"
fi
if nc -z -w 2 $IP $PORT &>/dev/null; then
echo -e "${GREEN}✓ ${IP}:${PORT} Ports accessible${NC}"
else
echo -e "${RED}✗ ${IP}:${PORT} Ports are not accessible${NC}"
fi
done
# Check Nginx error logecho -e "\n${YELLOW}[4/5] examine最近的NginxError log:${NC}"
if [ -f "/var/log/nginx/" ]; then
tail -n 20 /var/log/nginx/ | grep -iE "502|504|connect|refused|timeout" || echo "No recent ones found502/504Related Errors"
else
echo "Error log文件不存在"
fi
# Check system resourcesecho -e "\n${YELLOW}[5/5] examine系统资源use情况:${NC}"
echo -e "\nMemory usage:"
free -h
echo -e "\nCPUuse:"
top -bn1 | head -n 5
echo -e "\n磁盘use:"
df -h
echo -e "\n${YELLOW}=== Diagnosis completed ===${NC}"Summarize
502 and 504 errors are two common types of problems in Nginx proxy services, corresponding to the upstream server invalid response and response timeout. During the troubleshooting, you should follow the order of "first verify the upstream service status, then check the Nginx configuration, and finally analyze the system resources". These two types of errors can be effectively resolved by reasonably adjusting timeout parameters, optimizing application performance, and increasing system resources. It is recommended to configure a complete monitoring system in the production environment to monitor service status and performance indicators in real time so as to promptly discover and resolve potential problems.
This is the article about the detailed explanation and troubleshooting guide for Nginx 502 and 504 errors. For more information about Nginx 502 and 504 error resolution, please search for my previous articles or continue browsing the related articles below. I hope everyone will support me in the future!