Troubleshooting cheat sheet
A flat list of "I see X, do Y." For longer-form runbooks see
operations.md.
Sign-in / API
| Symptom |
Likely cause |
Fix |
401 Unauthorized after redirect from /Account/Login |
Cookie domain doesn't match PAAS_PLATFORM_HOSTNAME |
Ensure the URL in your browser matches the value in .env. |
Stuck redirect loop on /auth/login |
OIDC client secret rotated mid-session |
Clear cookies, sign in again. |
unable to obtain Let's Encrypt cert in cert-manager logs |
DNS / port-80 reachability |
Confirm DNS A record + port 80 is open. Switch PAAS_ACME_STAGING=true while iterating. |
| Can't see another org's apps |
Not a member |
Have an admin add you (/orgs/{org}/members). |
Git push
| Symptom |
Likely cause |
Fix |
Permission denied (publickey) |
SSH key not registered |
Account → SSH keys. |
Paas: invalid repo path |
Pushing to wrong remote |
Use exactly git@host:org/app.git. |
| Push succeeds, no deploy |
post-receive hook didn't fire |
docker compose logs git-server |
[paas] ERROR: API returned 401 from hook |
PAAS_INTERNAL_TOKEN mismatch |
Make sure both api and git-server see the same value. |
Build
| Symptom |
Likely cause |
Fix |
Stuck Queued for >1 min |
builder service not running |
docker compose ps builder |
| Build fails: "no Dockerfile" |
Repo doesn't have one at root |
Add a Dockerfile. Buildpacks not in v1. |
Build fails: "denied" pushing to registry:5000 |
Registry not reachable |
Check paas-control network, then docker compose restart registry. |
| Build is very slow |
First build per base image |
Subsequent builds will use the layer cache. |
Deploy / runtime
| Symptom |
Likely cause |
Fix |
Built but never goes Live |
Container starts but health probe fails |
App not listening on 0.0.0.0:$PORT. |
Failed, "container exited: 1" |
App crashes on startup |
See live logs panel; fix; redeploy. |
| 502 from URL |
No healthy upstreams |
See "App is Live but I get 502s" in operations.md |
| App restarts every few seconds |
OOMKilled |
Bump memoryMb (default 256). |
TLS
| Symptom |
Likely cause |
Fix |
Pending forever |
DNS not pointing here, or port 80 firewalled |
curl http://<host>/.well-known/acme-challenge/test from a third party. |
Failed, "rateLimited" |
Burned LE rate limits |
Set PAAS_ACME_STAGING=true, restart cert-manager. |
Browser warning even after Active |
Still on staging |
Set PAAS_ACME_STAGING=false, restart cert-manager, force renewal by removing/re-adding the domain. |
Database
| Symptom |
Likely cause |
Fix |
Stuck Provisioning |
Image pull failed |
docker compose logs orchestrator |
DATABASE_URL not in app env |
DB not named exactly main or not yet Ready |
Wait for Ready, then redeploy app. |
| App can't connect |
App is in a different network than paas-apps |
Should never happen — Orchestrator places all containers on paas-apps. If it does, file a bug. |