Valet shows 502 Bad Gateway on a .test site
502 Bad GatewayShort answer
Valet puts nginx in front of PHP-FPM. A 502 means nginx could not get an answer from PHP-FPM. Check whether the PHP-FPM socket exists, read Valet's nginx and PHP logs, then restart the services, switch to a PHP version that is installed, or reset the Valet install.
Fix it fast
1Find out which cause you have
Valet's PHP-FPM socket only exists while PHP is running properly. Check it, then read the end of Valet's nginx error log.
ls -l ~/.config/valet/valet.sock tail -n 30 ~/.config/valet/Log/nginx-error.log2Match what you see, then jump to its fix
- 1
valet.sock is missing from ~/.config/valetPHP-FPM is not runningFix - 2
502 after the PHP version Valet was using changed or was removedValet is set to a PHP version that is not installed any moreFix - 3
valet restart does not bring the socket back, and the logs show config or missing file errorsThe Valet install is brokenFix - 4
Errors only for sites inside Desktop, Documents or DownloadsThe site lives in a macOS protected folderFix
- 1
What does the error look like?
502 Bad GatewayA .test site shows 502 Bad Gateway while Valet is installed
Cause 1 of 4
PHP-FPM is not running
1Check
Valet's docs say the socket file exists only if PHP is running properly. Read the PHP-FPM logs for the reason it stopped.
ls ~/.config/valet/valet.sock
tail -n 30 ~/.config/valet/Log/fpm-php.www.log2Fix
Restart the Valet daemons.
valet restart3Verify
The socket is back and the site answers.
ls ~/.config/valet/valet.sock
curl -I http://myapp.testConfirmed by laravel.com
Cause 2 of 4
Valet is set to a PHP version that is not installed any more
1Check
Valet serves one PHP version at a time. See which PHP your shell and Valet use, and which PHP the site is isolated to.
valet which-php
valet isolated
brew list | grep php2Fix
Switch Valet to an installed version. Valet installs the version through Homebrew if it is missing. For one site only, use isolate in the site folder.
valet use php@8.3
# or, for the current site only
valet isolate php@8.33Verify
Valet now reports the version you chose and the site loads.
valet php --version
curl -I http://myapp.testConfirmed by laravel.com
Cause 3 of 4
The Valet install is broken
1Check
Valet can print diagnostics for support. Look for services that failed and files that are missing.
valet diagnose2Fix
Reset the installation as Valet's docs describe: reinstall the package and run install. Only if that fails, do the hard reset.
composer global require laravel/valet
valet install
# last resort
valet uninstall --force
valet install3Verify
The socket exists and the site responds.
ls ~/.config/valet/valet.sock
curl -I http://myapp.testConfirmed by laravel.com
Cause 4 of 4
The site lives in a macOS protected folder
1Check
Since macOS 10.14, those folders are restricted. Nginx can fail with server errors there unless it has Full Disk Access.
valet paths2Fix
Move the site outside the protected folders, for example to ~/Sites, then re-park or re-link it. Or give nginx Full Disk Access in macOS privacy settings.
mv ~/Documents/myapp ~/Sites/myapp
cd ~/Sites && valet park3Verify
Open the site again.
curl -I http://myapp.testConfirmed by laravel.com
How do I stop it coming back?
- After you change PHP versions, run valet use php@<version> before opening a site.
- Pin the version a project needs with a .valetrc file or valet isolate.
- Keep sites in ~/Sites or another folder macOS does not protect.
- Check valet.sock and the nginx log first, before changing any config.
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