Laravel

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.