Common Issues
Resolving Common Issues
If you are on this site, we’re sorry. We are working to create the most robust and easiest to use local development environment for Laravel – but Herd is still a tool early in its lifecycle, and we aren’t there yet. On this page, you’ll find common issues and a solution to resolve them.
If the documentation and the following tips don’t resolve your issue, please head over to the support section.
Herd Debug Logs
You can enable debug logs for Herd by starting it via the command line. The logs usually provide enough information so that you can either fix the problem yourself or create an issue in the community repository.
This command writes a Herd_Debug.log file to your log directory at ~/Library/Application Support/Herd/Log.
Bad Gateway
This can happen if the nginx configuration for your site is broken – to be honest, that’s normally a Windows problem, so how did you do that?
You can find the configuration files at the following path:
A good practice to fix the config file for a single site is by isolating the site to a specific PHP version or securing it with a TLS certificate. You can always switch back to the previous PHP version or unsecure the site but all these commands regenerate the configuration file to fix the issue.
If this does not help, please create an issue with the broken config file in the community repository.
404 Errors
If Herd can not properly detect a driver for your site or can’t find the site at all, Herd displays a custom 404 error page. This error page mostly has a useful hint how to fix the problem but it case it does not, the most common problem is that the directory of the project includes www in the name.
Herd strips www from directory names so that all sites are accessible via their domain with and without www prefix.
The solution to this is renaming the directory from www.your-site.com to your-site.com. This allows yout to access the site at http://your-site.com.test. If the site had specific configurations, you need to apply them again after this change because Herd treats this site as a new one.
DNS Errors
DNS errors happen when either dnsmasq isn’t running or when there is a different local DNS server installed on your machine.
Please make sure that dnsmasq is running and there are no errors in the logs. Dnsmasq gets started by the background service of Herd, please go to the helper service isn’t running to resolve the issue.
If there’s still a problem, another instance of dnsmasq could be running on your system. This mostly happens if you migrate from Valet to Herd and Herd isn’t able to remove the brew service. You can run brew services list to see if Homebrew still manages a dnsmasq instance and brew services stop dnsmasq to shut it down. After that, restart all Herd services and you should be good to go.
Herd shows the welcome screen on every start
This means that the helper service isn’t running in the background. Please follow The helper service isn’t running to resolve the issue.
The helper service isn’t running
Herd uses a helper service that runs with admin permissions to start dnsmasq and nginx. This comes with the benefit that there are no admin permissions required for the main application and if anyone finds a way to exploit Herd, they can not compromise your system.
To allow the Herd helper service to run in the background, please go to the “Login Items” section of your system settings and make sure that either Herd or Beyond Code GmbH (us) are allowed to run in the background.