General advice
It might sound trivial, but sometimes emptying a browsers cache, or restarting a browser might do wonders. Keep that in mind, whenever you run into problems with Valet.
- Empty your browsers’ cache. Even redirects might get cached
- Make sure you use a recent version of Valet. You get updates by running
composer global update - Look in the right place. Valet logs are actually here:
tail -f ~/.config/valet/Log/* - Are you using OPCache (for example preloading), Redis or Symfony (var/cache)? Make sure in your logs, that you’re not seeing cached errors. (by either restarting php, doing a
redis-cli flushallorrm -rf var/cache/* - Re-running
valet installwill not delete your projects. Sometimes it fixes things. Remember, that after re-install you’ll need to park your Sites folder again. brew services list,brew services info <service name>andbrew services restart <service name>can be helpful tools to debug Valet problems, as well.
1. Upgrading PHP can change your php.ini
I work on many computers and laptops, depending on where I am, but I have found myself, setting php memory limits more often than I should have been. The reason is that a brew upgrade of your locally installed PHP can sometimes mess up or overwrite your php.ini file or a new PHP release coming with a new php-memory-limits.ini file.
Solution
One simple approach is to backup your php.ini (or related config files) whenever you change them. What I like to do is, use mercurial or git to track changes. Of course this requires Mercurial to be installed (brew install mercurial} or alternatively you can use Git just as well.
cd /usr/local/etc/php/8.1/
hg init
hg add php.ini
or with Git
cd /usr/local/etc/php/8.1/
git init
git add php.ini
Even though these are local repositories, you have all the benefits of version control. you can see your modifications, as well as the ones done by brew or other processes such as pecl installs.
hg diff php.ini
2. Exotic document root names require a custom ValetDriver
Either you have a index.php in your project root, or inside a folder called public. Otherwise Valet can only find your bootstrap file if you’re using a supported CMS – by using so-called ValetDrivers.
You can actually verify if you have this problem, by appending your public folder name in the browser, eg. http://example.test/my-weird-docroot-path.
The concept of Valet’s Drivers is simple. They are plain PHP files a developer can understand. Take a look at the folders ~/.composer/vendor/laravel/valet/cli/drivers and ~/.config/valet/Drivers for that matter. While many CMS are supported out of the box, you might need a custom driver.
When you start a new project make sure you name your public folder public and you’re all set. For many other CMSs you will find pre-made drivers on gist.github.com. And if none of these steps work for you, write your own driver based off the SampleValetDriver.php.
3. 502 Bad Gateway Error
This one’s a bit tricky as it can have multiple causes.
Solution 1
The solution described in this comment worked for me several times:
sudo cp /usr/local/etc/php/8.1/php-fpm.d/valet-fpm.conf /usr/local/etc/php/8.1/php-fpm.conf
valet restart
Solution 2
If that didn’t do the trick for you, check your ~/.config/valet/Log/nginx-error.log file. If you see an *1 upstream sent too big header while reading response header from upstream error, then you should try to increase the fastcgi buffer sizes as described here.
Create ~/.valet/Nginx/all.conf with this:
~/.valet/Nginx/all.confproxy_buffer_size 4096k; proxy_buffers 128 4096k; proxy_busy_buffers_size 4096k;
Append this to /usr/local/etc/nginx/fastcgi_params
/usr/local/etc/nginx/fastcgi_paramsfastcgi_buffer_size 4096k; fastcgi_buffers 128 4096k; fastcgi_busy_buffers_size 4096k;
Solution 3
Depending on the size of your codebase or autoloader, you might also need to increase the PHP memory limits. Sometimes PHPs default of 512M just isn’t enough.
You can use php -I | grep memory to verify your current value.
If necessary, then edit /usr/local/etc/php/8.1/conf.d/php-memory-limits.ini and put an appropriate amount (for example 2G) for your system.
4. 504 Gateway Timeout Error
This article in german describes a solution: basically increasing all sorts of Nginx default timeouts to higher values, thus giving your request the time to it needs to finish. After adding the lines to the php block, restart valet.
5. Switching PHP versions
When you’re working on several projects, or maintaining old codebases. Not all of them may play well with your currently installed PHP version. One project might require PHP 7.4 another PHP 8.0 or 8.1.
As of Valet 9.x this is now a problem of the past. If you haven’t done so yet, make sure to upgrade from Valet 8.x to the latest 9.x version.
Now there are a ton of new features which make the use of different PHP versions really easy on a per-project level.
In old versions a simple valet use php@8.0 was not enough. While the CLI reported PHP to be 8.0 the browser did still process requests with the version you don’t want to use. My solution of the past has been to use either valet use, brew’s php-switcher or simply brew link to force the use of a specific version and then adjust 2 PATHs in my .zshrc profile. The great news is, that this is no longer necessary.
There’s:
- There’s the new
.valetphprcfile for use withvalet use. - Then, there’s a brand new
valet isolatewhich let’s you specify the version as well - Also there are new shortcuts
valet php,valet composerto make sure the version defined in a project is used on the CLI as well, without the need to unlink/link or switch PHP completely valet parkedandvalet isolatednow also tell the PHP version in use on a per project level
What is your opinion on developing with Valet? What problems do you run into? Which ones are missing from this list?
