Product Hunt🚀 We are live on Product Hunt! Support our launch & use code PHLAUNCH20 for 20% off Pro→
Stratosv1.7.0
Troubleshooting & Fixes• 3 min read

How to Fix 502 Bad Gateway Nginx (Valet & Herd) on macOS

Instant copy-paste terminal commands to fix broken PHP-FPM Unix domain sockets, crashed daemons, and Nginx upstream errors on macOS.

Why Does Nginx Return 502 Bad Gateway?

In macOS local development environments (like Laravel Valet, Laravel Herd, or custom Nginx setups), a 502 Bad Gateway error almost always means Nginx is running properly, but the upstream FastCGI process (PHP-FPM) has crashed, failed to spawn its Unix domain socket, or has mismatched user permissions.

💡 Instant Fix for Stratos Users: Open the Stratos menu bar icon, toggle PHP-FPM off and on, or click Site Doctor → Fix Permissions & Sockets. Stratos monitors Unix sockets automatically and cleans stale PIDs on launch.

Step 1: Check If PHP-FPM Is Running

Open Terminal on your Mac and verify whether any PHP-FPM processes are active:

ps aux | grep php-fpm

If the command only returns the grep line itself, your PHP-FPM daemon has crashed or failed to start.

Step 2: Kill Stuck Orphan Processes & Clear Stale Sockets

Often, an unclean macOS reboot or app crash leaves behind a dead Unix socket file or zombie PHP processes holding port 9000 or the socket path:

# Kill any hung PHP-FPM processes
sudo killall php-fpm 2>/dev/null || true

# For Laravel Valet: remove stale socket and restart
rm -f ~/.config/valet/valet.sock
valet restart

# For Laravel Herd: restart via CLI
herd restart

Step 3: Inspect Nginx Error Logs for the Root Cause

If restarting doesn't fix the 502 error, check the exact error Nginx received from the upstream socket:

# For Valet
tail -n 30 ~/.config/valet/Log/nginx-error.log

# For Herd
tail -n 30 ~/Library/Application Support/Herd/Log/nginx-error.log

# For Stratos
tail -n 30 ~/Library/Application Support/Stratos/logs/nginx-error.log

Common log entries and their solutions:

  • connect() to unix:.../php-fpm.sock failed (2: No such file or directory): PHP-FPM failed to boot. Reinstall the active PHP version or check php-fpm.conf for syntax errors.
  • Permission denied while connecting to upstream: Socket file was created by root instead of your local user. Run sudo chown $(whoami):staff ~/.config/valet/*.sock.
  • upstream sent too big header while reading response header: Increase fastcgi_buffer_size to 128k in your Nginx config.

The Permanent Solution: Switch to Stratos

Tired of debugging Homebrew PHP sockets, port 9000 collisions, and random 502 errors after every macOS Sequoia update? Stratos isolates each PHP version (8.1 through 8.5) into dedicated, sandboxed Unix sockets with automated health checks, stale PID cleanup, and instant 1-click restarts.

Download Stratos Free for macOS →