502 Bad Gateway on a Laravel Herd site on macOS
502 Bad GatewayShort answer
Herd's docs name two causes for a 502: PHP-FPM did not start properly, or the site's nginx configuration is broken. Restart Herd's services from the menu bar first. If that fails, regenerate the site's config by isolating the PHP version or securing the site, then read the log.
Fix it fast
1Find out which cause you have
Start Herd with file logging, reload the site, then read the log. It shows whether PHP-FPM or nginx is failing.
open /Applications/Herd.app --args --enable-logfile tail -n 50 ~/Library/Application\ Support/Herd/Log/Herd_Debug.log2Match what you see, then jump to its fix
- 1
The page says Herd is fixing this site, or shows a PHP-FPM error, or a notification says Herd couldn't restart PHPPHP-FPM did not start, or stopped respondingFix - 2
The 502 stays after PHP-FPM is healthy, and only one site is affectedThe site's nginx configuration is brokenFix - 3
Restart from the menu does not bring the site backHerd's services are stuck and need a hard stopFix
- 1
What does the error look like?
502 Bad GatewayHerd is fixing this site
Cause 1 of 3
PHP-FPM did not start, or stopped responding
1Check
Herd restarts PHP-FPM in the background by itself. If the restart fails, the page shows PHP-FPM's own error, which names the problem.
# read the error shown on the Herd page, or in Herd_Debug.log2Fix
Fix what the PHP-FPM error names, then use Restart in the Herd menu bar icon. That force-stops nginx, dnsmasq and PHP-FPM and starts them again.
# menu bar: Herd icon > Restart3Verify
Reload the site; it answers instead of 502.
curl -I http://myapp.testConfirmed by herd.laravel.com
Cause 2 of 3
The site's nginx configuration is broken
1Check
Open the site's generated nginx file in the Herd config folder.
ls ~/Library/Application\ Support/Herd/config/valet/Nginx2Fix
Regenerate the file: isolate the site to a specific PHP version, or secure it with a TLS certificate. Switching back to the previous version or unsecuring the site also rewrites it. Do this from Herd's site settings.
# in Herd site settings: isolate the PHP version, or secure the site3Verify
Reload the site after the change.
curl -I http://myapp.testConfirmed by herd.laravel.com
Cause 3 of 3
Herd's services are stuck and need a hard stop
1Check
Herd runs nginx, dnsmasq and PHP-FPM. A killall in the terminal force-stops them.
pgrep -fl 'nginx|php.*fpm|dnsmasq'2Fix
Force-stop with the documented command, then start Herd again. The list is the PHP versions Herd supports.
sudo killall nginx-arm64 dnsmasq-arm64 \
php82-fpm php83-fpm php84-fpm php85-fpm3Verify
Open Herd again and reload the site.
curl -I http://myapp.testConfirmed by herd.laravel.com
How do I stop it coming back?
- Keep Herd running; the docs note its page also reports if the app is not running.
- Change PHP settings through Herd, then restart, instead of editing generated files.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Back end
Composer says the gd extension is missing on a Laravel project
composer install or composer update stops on a package that requires ext-gd
Composer refuses to install a package that requires ext-gd when the PHP binary running Composer has no GD extension.
4 causes, each with a fixBack end
composer require maatwebsite/excel fails to install
Composer says the package needs an older PHP than the one installed
Composer refuses maatwebsite/excel when the PHP version or a PHP extension does not match what the package and PhpSpreadsheet need.
3 causes, each with a fixBack end
composer install says the lock file is not compatible and asks for update
Your lock file does not contain a compatible set of packages. Please run composer update.
composer install checked the locked packages against this machine's PHP and extensions and found a conflict.
3 causes, each with a fixBack end
composer require laravel/horizon fails: ext-pcntl is missing
laravel/horizon v1.1.0 requires ext-pcntl * -> the requested PHP extension pcntl is missing from your system
Horizon needs the pcntl extension, and Composer refuses to install it where PHP lacks that extension.
3 causes, each with a fixBack end
composer require laravel/passport stops with 'requirements could not be resolved'
... but these were not loaded, likely because it conflicts with another require.
Composer found no Passport release that fits your project at once.
4 causes, each with a fixBack end
Composer says the root composer.json requires a PHP version your PHP does not satisfy
Your requirements could not be resolved to an installable set of packages.
Composer compares the php constraint in your composer.json, or in a package, with the PHP that runs Composer.
3 causes, each with a fix