Maaz Zindani

Loading the index…

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

Valet shows 502 Bad Gateway on a .test site

Error502 Bad Gateway

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

  • Applies to Laravel Valet 4, macOS, Homebrew PHP 8.3
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

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

    1. 1valet.sock is missing from ~/.config/valetPHP-FPM is not runningFix
    2. 2502 after the PHP version Valet was using changed or was removedValet is set to a PHP version that is not installed any moreFix
    3. 3valet restart does not bring the socket back, and the logs show config or missing file errorsThe Valet install is brokenFix
    4. 4Errors only for sites inside Desktop, Documents or DownloadsThe site lives in a macOS protected folderFix

What does the error look like?

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

2Fix

Restart the Valet daemons.

valet restart

3Verify

The socket is back and the site answers.

ls ~/.config/valet/valet.sock
curl -I http://myapp.test

Confirmed by laravel.com

Did this fix it?

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 php

2Fix

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

3Verify

Valet now reports the version you chose and the site loads.

valet php --version
curl -I http://myapp.test

Confirmed by laravel.com

Did this fix it?

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 diagnose

2Fix

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 install

3Verify

The socket exists and the site responds.

ls ~/.config/valet/valet.sock
curl -I http://myapp.test

Confirmed by laravel.com

Did this fix it?

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 paths

2Fix

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 park

3Verify

Open the site again.

curl -I http://myapp.test

Confirmed by laravel.com

Did this fix it?

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