How to Diagnose and Resolve 502 Bad Gateway Errors in Nginx and PHP-FPM

An HTTP 502 Bad Gateway response indicates that Nginx, acting as a reverse proxy or gateway, received an invalid, truncated, or null response from the upstream application backend (most commonly PHP-FPM, Node.js, or Python Gunicorn).

Production Note: A 502 error is an upstream communication failure between web server and application backend, distinct from a 504 Gateway Timeout (which means the upstream took too long to answer).

At a Glance

1. Tail the primary Nginx error log to capture the exact upstream connection failure message.
2. Verify PHP-FPM / upstream service status with systemctl status.
3. Check UNIX domain socket permissions (listen.owner and listen.group).
4. Increase FastCGI buffer sizes if response headers exceed 4KB/8KB defaults.
5. Increase fastcgi_read_timeout if long-running scripts abort prematurely.
6. Verify and reload services.

Prerequisites

Before troubleshooting:

• Root or sudo SSH access to the web server.
• Access to /var/log/nginx/error.log and /var/log/php-fpm/ logs.
• Familiarity with Nginx virtual host configuration files.

Step 1: Inspect the Master Nginx Error Log

The Nginx error log pinpoint the exact root cause of the 502 response:

# Tail the Nginx error log in real-time
tail -f /var/log/nginx/error.log

Common error patterns and their remedies are detailed below.

Step 2: Resolve Upstream Daemon Crashes & Permissions

Case A: “connect() to unix:/run/php/php-fpm.sock failed (111: Connection refused)”

The PHP-FPM service is stopped or crashed.

# Check service status and restart
systemctl status php-fpm # or php8.2-fpm
systemctl restart php-fpm

Case B: “connect() to unix:/run/php/php-fpm.sock failed (13: Permission denied)”

Nginx worker user (nginx or www-data) lacks read/write access to the UNIX socket file.

Edit your PHP-FPM pool configuration (/etc/php-fpm.d/www.conf or /etc/php/8.x/fpm/pool.d/www.conf):

listen.owner = www-data
listen.group = www-data
listen.mode = 0660

Apply the changes:

systemctl reload php-fpm

Step 3: Optimize FastCGI Buffer and Timeout Limits

Case C: “upstream sent too big header while reading response header”

Large cookie headers or heavy framework metadata can exceed default Nginx buffers.

Add the following buffer directives inside the http {} or server {} block in nginx.conf:

fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;
fastcgi_busy_buffers_size 64k;

Case D: “upstream timed out (110: Connection timed out)”

Increase the FastCGI execution timeout:

fastcgi_read_timeout 300s;

Reload Nginx:

nginx -t && systemctl reload nginx

Troubleshooting

Problem: “502 Bad Gateway occurs only on POST requests or file uploads”

Possible cause: The PHP post_max_size or upload_max_filesize exceeds Nginx client_max_body_size, or PHP-FPM child workers are crashing with segmentation faults.

Check:

journalctl -u php-fpm -n 50 --no-pager

Solution: Align client_max_body_size in Nginx with upload_max_filesize in php.ini.

Verify the Configuration

Verify that Nginx configuration syntax is valid and test an HTTP request:

# Test Nginx syntax
nginx -t

# Test local HTTP response
curl -I http://localhost/

Expected output:

HTTP/1.1 200 OK

Production Checklist

• Inspected /var/log/nginx/error.log for upstream socket messages.
• Confirmed PHP-FPM daemon is active (systemctl status php-fpm).
• Verified socket owner and group match Nginx user.
• Increased FastCGI buffer sizes for large response headers.
• Validated Nginx syntax with nginx -t before reloading.

Frequently Asked Questions

What is the difference between 502 Bad Gateway and 504 Gateway Timeout?

A 502 error occurs when the backend server immediately crashes, refuses connection, or returns an invalid payload. A 504 error occurs when the backend server receives the request but fails to complete processing within the allocated timeout window.

Related Guides & Services

• How to Troubleshoot High Load on Linux Servers
• Server Performance Optimization & Caching
• Linux Server Administration & Support

Need Help Optimizing Web Servers?

If you run high-traffic web applications and need assistance tuning Nginx, PHP-FPM, and Redis object caching, contact our engineering team.

Contact Us