Fixing '502 Bad Gateway' (Nginx & PHP-FPM) in Laravel, Ubuntu & Docker
You deploy your Laravel application to an Ubuntu VPS or spin up an Nginx + PHP-FPM Docker stack, open your domain in the browser, and Nginx returns a blank white screen:
502 Bad Gateway
nginx/1.24.0 (Ubuntu)
Unlike a Laravel 500 Server Error—where PHP is running and writes a stack trace to storage/logs/laravel.log—a 502 Bad Gateway error means Nginx could not communicate with the upstream PHP-FPM process at all. Because the request never reached Laravel, storage/logs/laravel.log will be completely empty.
To find the exact failure, inspect the Nginx error log:
sudo tail -n 30 /var/log/nginx/error.log
Quick Diagnostic Reference
Match the exact error line from /var/log/nginx/error.log to jump to the solution:
| Nginx Error Log Message | Underlying Cause | Jump to Fix |
|---|---|---|
connect() to unix:/run/php/php8.2-fpm.sock failed (2: No such file or directory) |
PHP-FPM daemon is stopped, or Nginx points to an older PHP version’s socket | Fix 1 |
connect() to unix:/run/php/php8.3-fpm.sock failed (13: Permission denied) |
Socket ownership (listen.owner / listen.group) in www.conf does not match Nginx user |
Fix 2 |
connect() to 127.0.0.1:9000 failed (111: Connection refused) in Docker |
Nginx container is calling 127.0.0.1:9000 instead of the PHP service hostname (app:9000) |
Fix 3 |
upstream prematurely closed connection while reading response header |
Heavy Laravel route or queue dispatch exceeded fastcgi_read_timeout or crashed pm.max_children |
Fix 4 |
1. Fixing (2: No such file or directory) on Unix Sockets
When /var/log/nginx/error.log shows:
[crit] 14820#14820: *1 connect() to unix:/var/run/php/php8.2-fpm.sock failed (2: No such file or directory) while connecting to upstream
Nginx is looking for a Unix domain socket file that does not exist in /run/php/ (or /var/run/php/). This happens when the php-fpm service has crashed, or after you upgrade PHP (for example, from PHP 8.2 to PHP 8.3 or 8.4) and forget to update your Nginx site configuration.
Step 1: Check Which PHP-FPM Socket Exists on Disk
List the active sockets inside /run/php/:
ls -la /run/php/
Example output:
srw-rw---- 1 www-data www-data 0 Nov 03 08:15 php8.3-fpm.sock
-rw-r--r-- 1 root root 5 Nov 03 08:15 php8.3-fpm.pid
If no .sock file is listed, check the status of your installed PHP-FPM service and start it:
sudo systemctl status php8.3-fpm
sudo systemctl enable --now php8.3-fpm
(Security Note: If you recently upgraded your PHP version on Ubuntu to mitigate SAPI memory vulnerabilities, make sure your older PHP-FPM daemon is stopped and Nginx points to the patched binary. See our guide on How to Patch PHP2Shell (CVE-2026-109618 & CVE-2026-109619) in Ubuntu, Docker & Laravel).
Step 2: Align fastcgi_pass in Your Nginx Server Block
Open your site’s Nginx configuration file (/etc/nginx/sites-available/your-site.conf) and update the fastcgi_pass directive inside the location ~ \.php$ block to match the exact .sock version found in /run/php/:
location ~ \.php$ {
include snippets/fastcgi-php.conf;
# ❌ BROKEN: Points to old or non-existent socket
# fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
# ✅ WORKING: Matches active /run/php/php8.3-fpm.sock
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
include fastcgi_params;
}
Test the Nginx syntax and reload:
sudo nginx -t
sudo systemctl reload nginx
2. Fixing (13: Permission denied) on the PHP-FPM Socket
If the socket file exists, but /var/log/nginx/error.log reports:
[crit] 15210#15210: *4 connect() to unix:/run/php/php8.3-fpm.sock failed (13: Permission denied) while connecting to upstream
The Linux user running the Nginx worker processes does not have read/write permissions on the Unix socket created by PHP-FPM.
Step 1: Verify the Nginx Worker User
Check the user directive at the top of /etc/nginx/nginx.conf:
head -n 5 /etc/nginx/nginx.conf
On Ubuntu and Debian, this is typically user www-data;. (If you installed Nginx from the official upstream nginx.org repository or on RHEL/Rocky Linux, it may be set to user nginx;).
Step 2: Update listen.owner and listen.group in www.conf
Open your PHP-FPM pool configuration file:
sudo nano /etc/php/8.3/fpm/pool.d/www.conf
Ensure listen.owner, listen.group, and listen.mode are uncommented and match your Nginx user (www-data):
user = www-data
group = www-data
listen = /run/php/php8.3-fpm.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0660
Restart PHP-FPM so it recreates the socket with the updated permissions:
sudo systemctl restart php8.3-fpm
(Note: Once Nginx can talk to PHP-FPM, ensure your Laravel storage/ and bootstrap/cache/ directories are also owned by www-data so the application doesn’t throw a 500 file permission error next. Follow our guide on Fixing storage/logs/laravel.log Permission Denied in Linux & Docker).
3. Docker Compose: connect() to 127.0.0.1:9000 failed (111: Connection refused)
In a multi-container Docker Compose setup where Nginx runs in one container (webserver) and PHP-FPM runs in another container (app), Unix sockets aren’t shared unless you mount a shared volume. Instead, PHP-FPM listens on TCP port 9000.
If your Docker Nginx config has fastcgi_pass 127.0.0.1:9000;, Nginx looks for PHP-FPM inside the Nginx container itself and immediately fails with 111: Connection refused.
Step 1: Point fastcgi_pass to the Docker Service Name
Check the service name of your PHP-FPM container in docker-compose.yml:
services:
app:
build:
context: .
dockerfile: Dockerfile
expose:
- "9000"
nginx:
image: nginx:alpine
ports:
- "80:80"
depends_on:
- app
Inside your Docker Nginx configuration (docker/nginx/conf.d/default.conf), replace 127.0.0.1:9000 with app:9000:
location ~ \.php$ {
try_files $uri =404;
fastcgi_split_path_info ^(.+\.php)(/.+)$;
# ❌ BROKEN in multi-container Docker:
# fastcgi_pass 127.0.0.1:9000;
# ✅ WORKING: Uses the Docker Compose service name
fastcgi_pass app:9000;
fastcgi_index index.php;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}
Step 2: Ensure PHP-FPM Listens on 0.0.0.0:9000 Inside the Container
Official php:8.3-fpm Docker images bind to 9000 across all interfaces by default. If you built a custom Ubuntu/Debian image, verify /usr/local/etc/php-fpm.d/www.conf sets:
listen = 9000
Restart your Nginx container to apply the config:
docker compose restart nginx
(Note: Docker container loopback issues affect database and cache connections the exact same way. If your PHP container cannot reach MySQL or Redis after fixing Nginx, check Fixing SQLSTATE[HY000] [2002] Connection Refused and Fixing Redis Connection Refused on Port 6379).
4. Fixing upstream prematurely closed connection (Timeouts & Worker Exhaustion)
If your Laravel site loads normal pages fine, but throws a 502 Bad Gateway or 504 Gateway Time-out on heavy PDF exports, CSV imports, or third-party API calls, check the PHP-FPM slow log and pool limits:
sudo tail -n 30 /var/log/php8.3-fpm.log
If you see:
WARNING: [pool www] server reached pm.max_children setting (5), consider raising it
Step 1: Increase pm.max_children in www.conf
The default pm.max_children = 5 is too small for production traffic—if 5 concurrent requests wait on an external API or database query, the 6th visitor gets a 502 error.
Open /etc/php/8.3/fpm/pool.d/www.conf and tune the worker pool for your server’s RAM (assuming ~40–50MB per Laravel worker on a 2GB–4GB VPS):
pm = dynamic
pm.max_children = 25
pm.start_servers = 5
pm.min_spare_servers = 5
pm.max_spare_servers = 15
pm.max_requests = 500
Step 2: Align Nginx fastcgi_read_timeout with PHP max_execution_time
If a controller action legitimately needs 120 seconds (though heavy tasks should ideally be offloaded to Laravel Queues), increase both PHP’s request_terminate_timeout and Nginx’s fastcgi_read_timeout:
In /etc/nginx/sites-available/your-site.conf:
location ~ \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
fastcgi_read_timeout 120s;
fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;
}
Restart both services:
sudo systemctl restart php8.3-fpm
sudo systemctl reload nginx
Verification
Run this diagnostic command to confirm both Nginx and PHP-FPM are active, listening, and free of configuration syntax errors:
sudo nginx -t && sudo php-fpm8.3 -t && sudo systemctl is-active nginx php8.3-fpm
Expected output:
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
NOTICE: configuration file /etc/php/8.3/fpm/php-fpm.conf test is successful
active
active
Once both services report active, reload your application in the browser. If your application now loads but throws a BindingResolutionException on specific routes, check our guide on Fixing ‘Target class [Controller] does not exist’ in Laravel.