Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

502 Bad Gateway on a Laravel Herd site on macOS

Error502 Bad Gateway

Short 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.

  • Applies to Laravel Herd for macOS, PHP 8.3
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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.log
  2. 2Match what you see, then jump to its fix

    1. 1The 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. 2The 502 stays after PHP-FPM is healthy, and only one site is affectedThe site's nginx configuration is brokenFix
    3. 3Restart from the menu does not bring the site backHerd's services are stuck and need a hard stopFix

What does the error look like?

  • 502 Bad Gateway
  • Herd 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.log

2Fix

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 > Restart

3Verify

Reload the site; it answers instead of 502.

curl -I http://myapp.test

Confirmed by herd.laravel.com

Did this fix it?

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/Nginx

2Fix

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 site

3Verify

Reload the site after the change.

curl -I http://myapp.test

Confirmed by herd.laravel.com

Did this fix it?

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-fpm

3Verify

Open Herd again and reload the site.

curl -I http://myapp.test

Confirmed by herd.laravel.com

Did this fix it?

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 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 fix

Back 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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.