Skip to content
Butler

Troubleshooting

When something isn’t working, start here.

Run the health check

Section titled “Run the health check”
Terminal window
butler doctor

doctor inspects your setup end to end and reports what needs attention. The menu bar app shows the same checks in its Diagnostics section. Most issues below are things doctor will flag directly.

Sites won’t load at all

Section titled “Sites won’t load at all”

If no .test site loads:

  • Check Login Items. macOS won’t let Butler bind ports 80 and 443 until you allow it in System Settings → General → Login Items & Extensions. This is the single most common cause after a fresh install. Turn Butler on there.
  • Confirm the services are running. butler status should show the daemon and router as running. If not, butler system install re-registers them.
  • Reboot once after first setup if the privileged port binder hasn’t started — it comes up at login once you’ve allowed Butler.

A specific site doesn’t work

Section titled “A specific site doesn’t work”
  • Is it linked? butler sites should list it. If not, butler link it from the project folder.
  • Wrong PHP version? Check the version shown in butler sites. Pin the right one with butler isolate <name> <version> or in butler.yml.
  • Wrong web root? Set publicPath in butler.yml if the app serves from a subdirectory.
  • Read its logs. butler log <name> (or the app’s Logs section) shows what the web server and PHP are actually doing.

HTTPS shows a warning

Section titled “HTTPS shows a warning”

If https://your-app.test warns about the certificate:

  • Re-run trust. butler trust reinstalls Butler’s CA into the keychain. On a CLI-only install, run it under sudo in a terminal.
  • Re-secure the site. butler unsecure <name> then butler secure <name> re-issues the leaf certificate.
  • Restart the browser. Browsers cache certificate state; a full restart picks up a newly-trusted CA.

See HTTPS & trusted certs for the full picture.

Vite serves the wrong certificate

Section titled “Vite serves the wrong certificate”

If npm run dev serves stale or mismatched HTTPS certs for a site you secured with Butler, the usual cause is Laravel Herd. laravel-vite-plugin probes Herd’s config directory before Butler’s ~/.config/valet link, so Herd wins even when Butler’s setup is correct — and butler doctor’s Valet check can be green while Vite still reads Herd’s certs.

Run butler doctor: it warns when a Herd install is present and points at the shadowing directory. The fix is to uninstall Herd.app, or back up and remove ~/Library/Application Support/Herd/config/valet. See Running Herd alongside Butler.

Butler and Herd both installed

Section titled “Butler and Herd both installed”

Running both at once is fraught — they contend for php on your PATH and for ports 80 and 443, and Herd shadows Butler for Vite’s cert detection. Keep only one running at a time; see Running Herd alongside Butler.

A service won’t start

Section titled “A service won’t start”
  • Check its log. butler log <name> usually shows the reason (a port already in use, a data directory issue, and so on).
  • Restart it. butler restart <name>.
  • Reinstall the component if the binary looks broken: butler component remove <name> then butler install <name>.

Start over cleanly

Section titled “Start over cleanly”

To stop everything without losing anything:

Terminal window
butler shutdown

To remove Butler’s background jobs (keeping your state) or wipe it completely:

Terminal window
butler system uninstall          # remove background jobs
butler system uninstall --force  # also wipe state and downloads

Still stuck?

Section titled “Still stuck?”

Gather the output of butler doctor and the relevant butler log <name>, then open an issue on GitHub. Those two together tell the maintainers almost everything they need.