Troubleshooting
Start with the bounded release log, then verify the actual host boundary that failed.
Repository sync or Detect App fails
Check that Git is installed in Setup, the repository URL/protocol and HTTPS credential are correct, the branch exists, and the selected directory is inside the repository. Runtime detection reads only metadata from a shallow checkout. It cannot inspect an SSH repository until deploy-key support exists; use HTTPS for now.
Build or candidate health fails
Open the deployment log first. Confirm the selected repository directory has the expected package.json, start script, and application listener on Portal’s assigned PORT. Native projects must return 2xx or 3xx from the configured HTTP health path. Disable a health check only when the application genuinely has no HTTP endpoint.
Mail Setup reports ready but mail does not arrive
The readiness result describes outbound SMTP and local firewall policy only. Confirm the hostname is DNS-only, MX/SPF/DKIM/DMARC and PTR are correct, then send and receive a real message from an external provider. Check the cloud-provider firewall separately. Do not use the fixture Mail inbox as the receive test.
Domain or certificate fails
Check DNS from Domains, confirm port 80 reaches the target host, and temporarily remove CDN proxying/forced HTTPS before the first HTTP-01 certificate. Ensure another Nginx virtual host does not already claim the name. Portal preserves its prior managed Nginx configuration when TLS activation fails.
Portal update appears unhealthy
Check the three services, loopback health, and static HTTPS page: sudo systemctl is-active dashboard-portal hostmgr-deploy-helper nginx, curl -fsS http://127.0.0.1:3100/api/health, and curl -fsSI https://YOUR-PORTAL-DOMAIN/. Do not treat a health JSON response alone as the acceptance check.