Troubleshooting
First checks
- Make sure Docker is running.
- Open the Health Dashboard (
Cmd+D) to see service status. - Use the Activity Log (
Cmd+Opt+L) for detailed operations and errors. - Try Restart Nginx & PHP (
Cmd+Return) or Restart All Services (Shift+Cmd+Return).
Common issues
Site doesn’t load
- Confirm the site exists and the domain is correct.
- Ensure nginx is running.
- If you dismissed the admin prompt, re-save the site so Canopy can update
/etc/hosts.
SSL warning in the browser
- Trust the Canopy local CA in Keychain.
- Toggle SSL off and on to regenerate certs if needed.
500 / 502 / 504 for PHP sites
- Confirm the site config points to a valid PHP upstream (
fastcgi_pass php83:9000;, etc.). - Ensure the referenced PHP service is running.
- Canopy intercepts PHP upstream
500/502/504responses and serves a branded Canopy runtime error page with debugging context instead of a generic browser error. - If the site's runtime no longer matches its
composer.jsonrequire.php, check the Health Dashboard (Cmd+D) for a PHP Version Mismatch and switch the site to the recommended runtime.
Services slow to start after boot
- Canopy retries startup when Docker/OrbStack is late to become ready, so give it a moment after launch.
- If services still don't appear, confirm Docker/OrbStack is running, then use Restart All Services (
Shift+Cmd+Return).
Port conflicts
- Use Service Settings to change the conflicting port.
- Click Save & Restart so the container is recreated with the new mapping.
Database connection errors
- Make sure the service is running in the Services list.
- Check connection info (host, port, user, password) in the service panel.
Xdebug not connecting
- Verify your IDE is listening on port 9003 (or your configured port).
Project folder moved or missing
- Re-link the project from File → Link Project.
- If needed, remove and recreate the site using the folder’s new location.