Find the failing boundary
Start with evidence from the machine that runs the service.
Repository or permissions
Check Git identity, selected branch/directory, canonical HTTPS URL and credential host. Users need visibility plus the action grant in that organization. Permission changes invalidate sessions; sign in again. A token from another organization cannot be selected. Existing credentials in use must be unbound before deletion.
Build or runtime fails
Check installed executable, selected Node major, lockfile, start script and health path. For Node 20 verify better-sqlite3 after npm ci. Python needs python3-venv; PHP may need Composer/extensions; Go must satisfy go.mod with the installed compiler. Read candidate output before retrying. Missing database configuration can make the app exit before health checks.
Prisma CLI missing or preparation fails
First check the installed prisma package, version and bin. Portal 0.8.7/0.8.8 assumes build/index.js and can report a missing CLI for Prisma 8 even when dist/prisma.js exists. Portal 0.8.9 resolves this; creating another config or adding the same package again does not fix that Portal incompatibility. An actually missing dependency or broken config is an application fix.
Use the error checklist. Inspect the failed candidate and the active release separately; a failed deployment does not by itself mean the existing app is down.
Host activation or HTTPS fails
getent ahosts app.example.com
sudo nginx -t
sudo journalctl -u dashboard-portal -u hostmgr-deploy-helper --since '30 minutes ago' --no-pagerCheck DNS on the host, origin reachability, certificates and the upstream service. Local sandbox awaiting-host-activation is expected. An HTTP redirect to working HTTPS is not a failure. A successful /api/health response with a broken web page can indicate static-file traversal/read permissions.
A commit did not deploy
Compare the configured trigger mode, Auto deploy state, branch and release log. Polling can take five minutes. Actions mode intentionally waits for CI even after source sync. A hook 202 response means queued. Check the selected service type and its environment, runtime and optional-domain prerequisites and that a duplicate revision was not already deployed.
Worker exits or maintenance is busy
A Worker that exits after finishing a task fails long-running readiness. Use a supported runtime and inspect runtime logs, entry-point configuration, queue connectivity and SIGTERM handling. Do not add a fake HTTP server to satisfy health checks. For maintenance HTTP 503 or a refused update, let the current operation finish and retry; do not delete or replace the lock file. A recovery failure needs host inspection before retrying.