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.
502 / Bad Gateway 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.
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.