Fixing 502 Bad Gateway in Nginx and PHP-FPM for Laravel

event November 18, 2026
update Updated: November 16, 2026
timer 11 min
Laravel 502 Bad Gateway cover: the Nginx to PHP-FPM connection pipe with a broken joint and a red 502 badge
favorite 0

A 502 Bad Gateway means Nginx could not connect to PHP-FPM or received an invalid response; the error is generated by Nginx, not Laravel. So if you see a 502 while storage/logs/laravel.log stays empty, the request never reached PHP and you should read the Nginx error log. Before any blind systemctl restart, check these three things in this order: (1) is the PHP-FPM service alive? (2) does the socket path or TCP port you wrote in fastcgi_pass actually exist? (3) are the socket's ownership and permissions correct? In this article you will see exactly where in the path the request is stuck, which log to read and which command to run, plus one important detail: what looks like a 502 is sometimes really a 504 Gateway Timeout, and the cause is different.

What exactly is a 502, and where does it come from?

When Nginx hands a PHP request to FPM through fastcgi_pass, three things can break: the connection, reading the response header, and the response arriving within the allowed time. Nginx behaves differently in each case:

What you see in the Nginx error log What it means Which error it usually produces
connect() failed (111: Connection refused) while connecting to upstream FPM is stopped, or the fastcgi_pass path/port is wrong 502
connect() failed (13: Permission denied) while connecting to upstream Nginx is not allowed to open the socket 502
upstream sent too big header The response header is larger than fastcgi_buffer_size 502
recv() failed (104: Connection reset by peer) FPM restarted mid-response 502
no live upstreams while connecting to upstream The upstream block is empty or all of its servers failed 502
upstream timed out (110: Connection timed out) The response did not arrive in time usually 504

The 502/504 split comes straight from the Nginx source: a timeout ends in NGX_HTTP_GATEWAY_TIME_OUT (504) while the other failures end in NGX_HTTP_BAD_GATEWAY (502) (ngx_http_upstream.c). Practical result: if the site hangs for a while and then errors out, look for a timeout; if it errors instantly, look for a connection problem.

Why do Laravel projects hit this more often?

Laravel plays no role in the 502 itself; the problem lives in the Nginx ↔ PHP-FPM layer. Still, three common habits of Laravel projects raise the odds:

  • Large response headers: with Livewire or Inertia and many cookies, the response header can exceed Nginx's default fastcgi_buffer_size (which the Nginx docs define as 4k|8k), so you get upstream sent too big header.
  • The worker pool runs out: slow queries or heavy queues can keep FPM busy up to its pm.max_children limit; new requests then time out or get no response. If you have not tuned queues yet, start with Fixing Laravel Queues with Supervisor; stuck workers are one of the heaviest loads on FPM.
  • Operations on production: running composer install or migrations as root can change file and socket ownership, and Nginx can no longer connect.

First, identify which platform you are on

The request path differs per environment, and that is the main reason debugging stalls:

Platform How PHP is reached Where the 502 usually comes from
VPS with Nginx + FPM fastcgi_pass unix:/run/php/php8.3-fpm.sock or fastcgi_pass 127.0.0.1:9000 Wrong socket path (especially after a PHP upgrade), permissions, FPM stopped
cPanel / DirectAdmin The panel manages FPM; each user has its own pool You cannot change pool settings directly; follow up through the panel's PHP management or your host's support
Docker fastcgi_pass app:9000 (TCP between containers) Wrong service name in docker-compose.yml, or the FPM container is in a restart loop

On a VPS the overall path is:

Browser → Nginx (:80/:443)
   ├─ serves static files from public/
   └─ other requests → fastcgi_pass unix:/run/php/php8.3-fpm.sock
        → FPM pool (up to pm.max_children workers)
        → Laravel (public/index.php) → response to Nginx → browser

Two facts from the PHP source itself: in php-src's www.conf.in, the default listen is 127.0.0.1:9000 and the suggested listen.mode is 0660; but Ubuntu packages usually configure a unix socket such as /run/php/php8.3-fpm.sock. So what your server actually uses must be read from your own pool config, not guessed.

Step 1: diagnose without restarting

These commands change nothing; the goal is to find exactly where the path is broken:

# 1. PHP-FPM service status (adjust the PHP version)
sudo systemctl status php8.3-fpm --no-pager

# 2. Does the socket exist at all?
ls -la /run/php/

# 3. Socket ownership and permissions
stat /run/php/php8.3-fpm.sock

# 4. Where does Nginx point? (nginx -T dumps all included configs)
sudo nginx -T 2>/dev/null | grep fastcgi_pass

# 5. The latest errors
sudo tail -n 50 /var/log/nginx/error.log

How to read the output:

  • systemctl status: active (running) means the service is fine and the problem is elsewhere. inactive (dead) or failed means run journalctl -xeu php8.3-fpm --no-pager; it usually reveals a syntax error in the pool config.
  • ls /run/php/: if the socket file is missing, the service never started or listen in the pool config points elsewhere. Make sure the path shown by nginx -T matches the real file; a mismatch between the two is the most common cause of a 502 right after a PHP upgrade. By the way, nginx -T is not just for fastcgi; it surfaces other Nginx config problems too, such as Laravel's 404 storage link error in Nginx.
  • stat: healthy output on Ubuntu looks like Access: (0660) Uid: ( 33/www-data) Gid: ( 33/www-data); if the group does not match the Nginx worker user, you get the Permission denied error.
  • One more direct test, without Nginx: open a clean connection to FPM itself with cgi-fcgi (part of the libfcgi-bin package on Ubuntu):
sudo cgi-fcgi -bind -connect /run/php/php8.3-fpm.sock || echo "SOCKET FAIL"
sudo cgi-fcgi -bind -connect 127.0.0.1:9000 || echo "TCP FAIL"

If SOCKET FAIL or TCP FAIL prints, the problem is in FPM itself, not the Nginx config; before changing anything, read the FPM log and journalctl.

Step 2: quick fix (when you are having downtime)

The rule for this stage: know why you are restarting. Every blind restart cuts in-flight requests.

2.1 If FPM is stopped

sudo systemctl start php8.3-fpm
sudo systemctl enable php8.3-fpm

If it fails to start, read journalctl -xeu php8.3-fpm --no-pager for a syntax error, fix it, and start again.

2.2 If you see Permission denied

Let Nginx reach the socket. You have two options: add the Nginx worker user to the socket's group, or set the socket ownership in the pool config:

# /etc/php/8.3/fpm/pool.d/www.conf
listen.owner = www-data
listen.group = www-data
listen.mode = 0660

Then:

sudo systemctl reload php8.3-fpm

Key point: reload re-reads the config and, unlike a restart, does not interrupt in-flight requests. For most fixes a reload is enough.

2.3 If every site returns 502 after a PHP upgrade

After upgrading from PHP 8.2 to 8.3, the socket path changes from php8.2-fpm.sock to php8.3-fpm.sock, but the Nginx config still points at the old path:

# Current socket paths
ls /run/php/

# Fix the config, and always test before reloading
sudo sed -i 's|php8.2-fpm.sock|php8.3-fpm.sock|g' /etc/nginx/sites-enabled/*
sudo nginx -t && sudo nginx -s reload

Always run nginx -t first; if there is a syntax error, the reload is refused, the old config stays in place, and the site does not go down.

Step 3: root causes, when the 502 keeps coming back

If the quick fix worked but the 502 returns later, you have a structural cause. Three of the most common:

3.1 Tuning the pool's pm.* values

The defaults in php-src's www.conf are pm = dynamic, pm.max_children = 5, pm.start_servers = 2, pm.min_spare_servers = 1, pm.max_spare_servers = 3 and pm.max_requests = 0; a small pool with no worker recycling. For a Laravel site, raise these based on your server's RAM. As a hypothetical example (not a copy-paste recipe): a 4 GB RAM server with roughly 2 GB for PHP, assuming 50 MB per request, works out to about pm.max_children = 40, plus some headroom:

# Example only; set the numbers from your server's real RAM
pm = dynamic
pm.max_children = 40
pm.start_servers = 10
pm.min_spare_servers = 5
pm.max_spare_servers = 20
pm.max_requests = 500

pm.max_requests recycles each worker after n requests, which contains potential memory leaks in third-party libraries. Remember: editing these files changes nothing by itself; run systemctl reload php8.3-fpm so the master process re-reads the config.

3.2 Header buffer size in Nginx

Per the Nginx docs, the defaults are fastcgi_buffer_size 4k|8k and fastcgi_buffers 8 4k|8k (the 4k or 8k unit depends on the OS page size). Laravel's response headers (especially with Inertia) can be larger than that:

# in an http, server or location block
fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;

Tune these to your real header sizes, not to an arbitrary maximum.

3.3 OPcache after a deploy

From php-src, OPcache's defaults are opcache.enable = 1, opcache.validate_timestamps = 1 and opcache.revalidate_freq = 2. Files are checked every 2 seconds by default, so after a deploy the new code eventually loads. But if someone set opcache.validate_timestamps = 0 anywhere, PHP keeps serving the old code from memory until the next reload; that produces strange post-deploy behavior. For frequent deploys, run systemctl reload php8.3-fpm after each one so the new code is definitely served.

3.4 How to notice faster next time

Since Laravel 11 there is a built-in health route at /up (Laravel 12.x Deployment docs): it returns 200 if the application has booted without exceptions and 500 otherwise. You can set up a simple once-a-minute check that alerts you when a healthy response stops coming:

# in crontab; every minute
* * * * * curl -fsS http://localhost/up >/dev/null || echo "502 ALERT: site down"

Remember this line only fires if your server's crontab is set up correctly; after adding it, watch the output for a few minutes to confirm it really works.

Quick reference: one action per error

Nginx error Meaning Main action
Connection refused FPM stopped or wrong path systemctl status php8.3-fpm and ls /run/php/
Permission denied Socket ownership Set listen.owner/group in the pool and reload
upstream sent too big header Header larger than the buffer Raise fastcgi_buffer_size and fastcgi_buffers
Connection reset by peer FPM restarted mid-response Check the FPM log and journalctl
no live upstreams Empty upstream or all failed Review the upstream block and fastcgi_pass
upstream timed out Slow response (usually 504) Manage slow queries and pool capacity

When is a full restart actually needed?

A reload is enough for most fixes. A full restart is usually needed when:

  • You made a structural change to php.ini (such as memory_limit).
  • You installed a new PHP extension.
  • You changed OPcache settings substantially.

And never kill -9 FPM processes; it cuts active requests mid-flight and can leave the service in a worse state. Test frequent code changes somewhere like staging before production; for common post-deploy errors, see Fixing the Vite manifest error in production.

FAQ

1. What is the difference between 502 and 504? 502 means Nginx could not connect or got an invalid response; 504 means it connected but the response did not arrive within fastcgi_read_timeout (60 seconds by default). If the site hangs for a few seconds before erroring, it is probably a 504 and you should look at timeouts and slow code.

2. Why is storage/logs/laravel.log empty while the site returns 502? Because the 502 happens before the request reaches PHP; the failure is in the Nginx-to-FPM connection layer. Read the Nginx error log (/var/log/nginx/error.log); the connect() failed or upstream sent too big header patterns are right there.

3. How do I know if PHP-FPM uses a socket or TCP? Look for listen in the pool config (for example /etc/php/8.3/fpm/pool.d/www.conf). If it starts with unix:, it is a socket; if it is 127.0.0.1:9000, it is TCP. php-src's own default is TCP, and Ubuntu packages usually set a socket.

4. Every site returns 502 after a PHP upgrade. What now? Almost always the socket path in the Nginx config is outdated. Find the new path with ls /run/php/, fix fastcgi_pass, then run nginx -t and nginx -s reload.

5. Does changing pm.max_children apply without a reload? No. The value is written in the pool file but stays inactive until FPM re-reads the config. Run systemctl reload php8.3-fpm; unlike a restart, a reload does not interrupt active requests.

6. What is the /up route and what does it have to do with 502? Since Laravel 11 there is a built-in health route that returns 200 when the app boots without exceptions and 500 otherwise. If /up errors while other routes return 502, the problem is in the Nginx-to-FPM connection, not one specific route.

Wrap-up

Nginx generates the 502, not Laravel; the check order is always the same: the PHP-FPM service, the path and type of connection in fastcgi_pass, socket ownership and permissions, then buffer size and pool capacity. With this order you resolve most cases without a blind restart. If you want faster debugging, try Nyx; and if you have a Laravel project whose troubleshooting has become heavy, tell us via Captain Code's contact page.

Captain Code
verified
Author

Captain Code

View Profile arrow_forward

Passionate about coding and sharing knowledge. We strive to create the best content for you at Captain Code.

Was it useful? Like it 👋
Share:

FAQ

What is the difference between 502 and 504?

502 means Nginx could not connect or got an invalid response; 504 means it connected but the response did not arrive within fastcgi_read_timeout (60 seconds by default). If the site hangs for a few seconds before erroring, it is probably a 504 and you should look at timeouts and slow code.

Why is storage/logs/laravel.log empty while the site returns 502?

Because the 502 happens before the request reaches PHP; the failure is in the Nginx-to-FPM connection layer. Read the Nginx error log (/var/log/nginx/error.log); the connect() failed or upstream sent too big header patterns are right there.

How do I know if PHP-FPM uses a socket or TCP?

Look for listen in the pool config (for example /etc/php/8.3/fpm/pool.d/www.conf). If it starts with unix:, it is a socket; if it is 127.0.0.1:9000, it is TCP. php-src's own default is TCP, and Ubuntu packages usually set a socket.

Every site returns 502 after a PHP upgrade. What now?

Almost always the socket path in the Nginx config is outdated. Find the new path with ls /run/php/, fix fastcgi_pass, then run nginx -t and nginx -s reload.

Does changing pm.max_children apply without a reload?

No. The value is written in the pool file but stays inactive until FPM re-reads the config. Run systemctl reload php8.3-fpm; unlike a restart, a reload does not interrupt active requests.

What is the /up route and what does it have to do with 502?

Since Laravel 11 there is a built-in health route that returns 200 when the app boots without exceptions and 500 otherwise. If /up errors while other routes return 502, the problem is in the Nginx-to-FPM connection, not one specific route.

Captain Code

Want this built for your project?

Hire Captain Code to take the project from here, or try Nyx and debug it with the AI assistant.

forum

Comments

lock_person

Login to comment

To join the conversation, please log in to your account first.

login Login
chat_bubble_outline

No comments yet

Be the first to share your thoughts on this post!