Troubleshooting

bitl doctorbitl status

my-app.test doesn’t load

Work through it in order:

1. Is the site registered? bitl list. If not, bitl link from the project directory.
2. Is the stack up? bitl status should show nginx, PHP-FPM and dnsmasq running. If not: bitl start.
3. Does the name resolve?

   dscacheutil -q host -a name my-app.test    # expect 127.0.0.1cat /etc/resolver/test                     # expect: nameserver 127.0.0.1

   If the resolver file is missing, recreate it and flush the cache:

   sudo mkdir -p /etc/resolverecho 'nameserver 127.0.0.1' | sudo tee /etc/resolver/testsudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

4. Still nothing? Check the error log: bitl logs nginx.

Port 80, 443 or 53 is already in use

bitl doctor names the process. The usual suspects are Laravel Herd, Valet, a Homebrew nginx/Apache, Docker Desktop publishing :80, or another dnsmasq.

sudo lsof -nP -iTCP:80 -sTCP:LISTENsudo lsof -nP -iUDP:53brew services stop nginx dnsmasq     # if they are Homebrew'svalet stop                           # if Valet is installed

Then bitl restart.

Browser says the certificate isn’t trusted

1. Make sure the site is secured: bitl list shows ✔ under SSL. If not, bitl secure my-app.
2. Trust BitL's CA system-wide — once:

   sudo security add-trusted-cert -d -r trustRoot \  -k /Library/Keychains/System.keychain \  ~/Library/Application\ Support/BitL/ssl/ca/BitLCA.pem

3. Quit and reopen the browser — they cache trust decisions.
4. Firefox: set security.enterprise_roots.enabled to true in about:config.

bitl doctor reports SSL CA trusted once this works. If it isn't, doctor prints the exact security command for your machine.

A service keeps crashing

bitl services health mysqlbitl logs ~/Library/Application\ Support/BitL/log/mysql-mysql.stderr.log

When BitL recognises the cause it says so in the Services view with a Copy Fix button. The most common case: a service installed via Homebrew stops starting after brew upgrade removed a library it links against. The fix is brew reinstall <formula> for the formula BitL names.

Another frequent one is a port clash with a second copy of the same database. BitL's defaults (3360, 5440, 6380 …) avoid the stock ports, but if you changed them, check with bitl services.

php -v shows the wrong version

Your terminal is finding another PHP first — usually Homebrew's in /opt/homebrew/bin.

which -a phpbitl php path --checkbitl php path --install && source ~/.zshrc

Websites use the PHP of their FPM pool, not your shell. If a site runs the wrong version, check bitl php pools and any isolation from bitl isolate.

502 Bad Gateway

nginx is up but PHP-FPM for that site's version isn't answering.

bitl php pools            # is the pool for this PHP version running?bitl logs phpbitl restart

If the site is isolated to a version you have since uninstalled, reinstall it (bitl php install 8.2) or isolate to one you have.

Emails don’t show up

• bitl mail status — is the SMTP server running? If not, bitl debug start.
• Your app must send to 127.0.0.1:2525 with no encryption. Laravel: MAIL_MAILER=smtp, MAIL_HOST=127.0.0.1, MAIL_PORT=2525, and clear the config cache (bitl artisan my-app config:clear).
• Queued mail only goes out when a queue worker runs.

BitL keeps asking for my password

The privileged helper isn't registered, so each system change needs a new prompt. Open Settings → General → Privileged Helper and click Install (or Reinstall). If macOS blocked it, allow BitL under System Settings → General → Login Items & Extensions.

Start over

bitl stopbitl services stop --allbitl unlink --all --yesbitl init            # recreate directories, configs and the CAbitl start

Still stuck?

Every command explains itself: bitl help <command> or bitl <command> --help. When you report a problem, include the output of bitl doctor and bitl --version.