Resolving 502 Bad Gateway Errors in Nginx and PHP-FPM Configuration: Transition from Port to Unix Socket

When deploying web servers based on Nginx and PHP-FPM, the 502 Bad Gateway error is a common yet frustrating issue. This error typically indicates that Nginx cannot communicate properly with the backend PHP-FPM processes. This article analyzes the root causes and provides detailed solutions based on an actual case study.

Problem Context and Error Symptoms

The user reported encountering 502 Bad Gateway errors on an Ubuntu Server 11.10 64-bit system running on an Amazon EC2 t1.micro instance with Nginx and PHP-FPM. Key symptoms included: errors appearing when accessing the domain root directory, php5-fpm service hanging during restart attempts, and the server functioning normally previously when PHP was not working.

Configuration Analysis: Identifying Root Causes

Examination of the user's Nginx configuration revealed a critical issue: in the location block, the fastcgi_pass directive pointed to unix:/var/run/php5-fpm.pid. This is a common configuration error, as .pid files contain process IDs rather than Socket files for inter-process communication.

The correct approach is to check PHP-FPM's actual listening configuration. In Ubuntu systems, PHP-FPM pool configuration is typically located in the /etc/php5/fpm/pool.d/www.conf file. Here, the listen parameter value must be examined, as it determines how PHP-FPM accepts FastCGI requests.

Solutions: Matching Listening Methods

There are two main approaches to resolve this mismatch:

Method 1: Modify Nginx Configuration to Match PHP-FPM's Socket

First, check PHP-FPM's listening configuration:

grep '^listen' /etc/php5/fpm/pool.d/www.conf

If the output shows something like listen = /var/run/php5-fpm.sock, PHP-FPM is using a Unix Socket. In this case, modify the fastcgi_pass directive in Nginx configuration:

# Incorrect configuration
fastcgi_pass unix:/var/run/php5-fpm.pid;

# Correct configuration
fastcgi_pass unix:/var/run/php5-fpm.sock;

Complete Nginx location block configuration example:

location ~ \.php$ {
    root /var/www/html;
    fastcgi_pass unix:/var/run/php5-fpm.sock;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include fastcgi_params;
}

Method 2: Modify PHP-FPM Configuration to Use TCP Port

Alternatively, modify PHP-FPM configuration to listen on a TCP port (typically port 9000), then adjust Nginx configuration accordingly:

# Modify /etc/php5/fpm/pool.d/www.conf
listen = 127.0.0.1:9000

Then modify Nginx configuration:

fastcgi_pass 127.0.0.1:9000;

Verification and Troubleshooting

After configuration changes, restart the relevant services:

sudo service php5-fpm restart
sudo service nginx restart

Verify that PHP-FPM is listening at the correct location:

# Check Unix Socket
ls -la /var/run/php5-fpm.sock

# Or check TCP port
netstat -tlnp | grep 9000

Permission and Ownership Issues

When using Unix Sockets, permission issues can cause connection failures. Ensure Nginx worker processes (typically the www-data user) have access to the Socket file:

# Check Socket file permissions
ls -l /var/run/php5-fpm.sock

# Typical correct permissions
srw-rw---- 1 www-data www-data 0 [date] /var/run/php5-fpm.sock

If permissions are incorrect, adjust the listen.owner, listen.group, and listen.mode parameters in PHP-FPM configuration.

Error Log Analysis

When encountering 502 errors, checking error logs is crucial for diagnosis:

# Nginx error log
tail -f /var/log/nginx/error.log

# PHP-FPM error log
tail -f /var/log/php5-fpm.log

Common error messages include:

• connect() to unix:/var/run/php5-fpm.sock failed (2: No such file or directory) - Socket file doesn't exist
• connect() to unix:/var/run/php5-fpm.sock failed (13: Permission denied) - Permission issues
• upstream timed out (110: Connection timed out) - Connection timeout

Performance Considerations: Socket vs Port

Choosing between Unix Socket and TCP port involves performance and security trade-offs:

• Unix Socket: Generally faster as it avoids TCP/IP stack overhead; limited to local communication, offering higher security
• TCP Port: Enables cross-server communication; easier to monitor and debug; may be slightly slower

For most single-server deployments, Unix Socket is recommended due to better performance. However, in distributed environments requiring cross-server communication, TCP ports may be necessary.

Configuration Best Practices

1. Maintain Configuration Consistency: Ensure Nginx's fastcgi_pass exactly matches PHP-FPM's listen setting

2. Use Standardized Paths: Follow distribution default path conventions to reduce configuration errors

3. Implement Monitoring: Set up monitoring systems to detect PHP-FPM process status and Socket/port availability

4. Document Configurations: Record all custom configurations to facilitate troubleshooting and team collaboration

Conclusion

502 Bad Gateway errors typically stem from communication issues between Nginx and PHP-FPM, most commonly due to listening method mismatches. By systematically checking configurations, verifying service status, and analyzing error logs, these problems can be effectively diagnosed and resolved. Understanding the differences between Unix Sockets and TCP ports, and selecting the appropriate communication method based on specific requirements, is key to building stable PHP application environments.

The solutions provided in this article not only address specific configuration errors but also establish a general troubleshooting framework applicable to various Nginx and PHP-FPM configuration scenarios. Remember that configuring web servers is a meticulous process requiring careful verification at each step to ensure all components work together correctly.