Troubleshooting

Most problems show up in one of three places: the services, the health check or a log. Start there, then look for your problem below.

First checks#

cove status                    # is each service running?
cove health                    # a full check-up, changes nothing
cove log mysite                # a site's own log, then its access log

cove status shows whether FrankenPHP, MariaDB and Mailpit are running, plus PostgreSQL and Redis once a Laravel app has set them up. If one is down, cove enable starts them all again.

cove health goes further. It reports on the services, FrankenPHP's process and its last exit, crashes in the last day and what caused them, how full PHP's OPcache is, leftovers on disk, and what other machines on your network can reach. It recommends a fix for anything it finds, and changes nothing itself.

cove log on its own shows the shared PHP error log. With a site name it shows that site's own log first (WordPress's debug.log, or a Laravel app's newest log), then its access log. Add -f to follow it as it grows. The dashboard shows the same logs, parsed and filtered by site.

A certificate warning#

Every site is served over HTTPS with a certificate from Cove's own local certificate authority. The installer trusts it for you. If a browser still says the connection isn't private, run:

cove trust

It adds Cove's root certificate to your system's trust store. On Linux, where browsers keep certificate stores of their own, it adds it to every one it can find too: Chrome, Chromium, Brave and Edge, Firefox profiles, and snap and Flatpak browsers. If a browser was open while it ran, restart the browser.

If that doesn't do it, trust the certificate by hand. On macOS, open ~/Library/Application Support/Caddy/pki/authorities/local/root.crt in Keychain Access and set it to Always Trust. On Ubuntu or Debian:

sudo cp ~/.local/share/caddy/pki/authorities/local/root.crt /usr/local/share/ca-certificates/caddy.crt
sudo update-ca-certificates

On Fedora, Rocky Linux or RHEL:

sudo cp ~/.local/share/caddy/pki/authorities/local/root.crt /etc/pki/ca-trust/source/anchors/caddy.crt
sudo update-ca-trust

Opening a site on your phone? cove lan trust explains how to trust the certificate there. See Sharing.

Ports 80 or 443 are taken#

Another local tool, like Local, Studio, DevKinsta or MAMP, may already be using the standard web ports. The installer notices and asks what to do:

⚠️  Port Conflict Detected
   Port 80 is in use by: Local
   Port 443 is in use by: Local

❯ Use alternative ports (8090 / 8453) — run alongside other tools
  Pick custom ports
  Proceed with 80/443 anyway
  Cancel installation

With the alternative ports, your sites are at addresses like https://mysite.localhost:8453. You can change your mind at any time:

cove ports                     # a menu: keep, default or custom
cove ports --http=80 --https=443
cove ports --dry-run           # what a change would do, changing nothing

When the port changes, Cove rewrites the addresses stored in every WordPress site's database, and moves each Laravel app's APP_URL with it, so your sites keep working. More in HTTPS and domains.

A site won't load#

First check that the services are up with cove status. Then rebuild the web server's configuration from your sites:

cove reload

If the new configuration has a mistake in it, the web server refuses it. Cove then prints the reason, keeps serving the configuration that worked, and saves the refused one at ~/Cove/Caddyfile.rejected for you to look at. The usual cause is a site's custom Caddy rules: see them with cove directive list, and fix them with cove directive update or remove them with cove directive delete.

If the page loads but shows an error, the site's log has it: cove log mysite.

WSL2#

systemd isn't running#

Cove runs its services through systemd, so the installer stops if WSL hasn't turned it on. Add these lines to /etc/wsl.conf inside your Linux distribution:

[boot]
systemd=true

Then run wsl --shutdown in PowerShell, open the distribution again, and run cove install.

Sites don't open in a Windows browser#

WSL2 has a network of its own, so Windows doesn't know where mysite.localhost is. Inside WSL, run:

cove wsl-hosts

It prints a PowerShell line to run as Administrator, which adds your sites to Windows' hosts file, and the steps to trust Cove's certificate in Windows. The line names the sites you have now, so run it again after you add one.

A database error when adding a site#

Check that MariaDB is running with cove status. If it isn't, cove enable restarts it along with the other services. If it is running and Cove still can't reach it, check that ~/Cove/config has the right DB_USER and DB_PASSWORD.

Sites broke after a port change#

If you changed ports with --skip-urls, your WordPress sites still have the old port stored in their databases. Change the ports back, then forward again, this time without --skip-urls, and Cove rewrites every site's addresses on the way. To fix a single site by hand instead:

cove wp mysite option update siteurl https://mysite.localhost:8453
cove wp mysite option update home https://mysite.localhost:8453

FrankenPHP keeps crashing#

The web server comes back on its own: the system restarts it after a crash, and Cove's watchdog restarts it if it stops answering. You may only notice a failed request or two. cove health lists the crashes of the last day and what caused each one.

• The crash handler. One of FrankenPHP's bundled extensions replaces its crash handler with one that turns a fault in a single request into a crash of the whole server. cove signals checks it and cove signals apply puts the right one back. The watchdog already does this each time the server starts.
• A full OPcache. Every site shares one PHP cache, and a crowded one can crash the server. cove opcache shows how full it is, cove opcache sites shows which sites fill it, and cove opcache set makes it bigger. See PHP.

Still stuck?#

Open an issue on GitHub ↗. Include what you ran, what it printed, and the output of cove version and cove health.