1.8 Phase 1 Troubleshooting
Quick reference for common bootstrap-time failures. The full operations runbook
(docs/operations/OPERATIONS_RUNBOOK.md in the repo) covers steady-state issues.
Database
| Symptom | Cause | Resolution |
|---|
psql: connection refused from your laptop | Firewall rule missing for your public IP | Re-add via az postgres flexible-server firewall-rule create. |
permission denied to create extension citext | Role lacks Postgres-admin privilege | GRANT azure_pg_admin TO rcm_master_admin; then re-run migrations. |
| Migration X is "stuck" | knex_migrations_lock.is_locked = true from a prior crash | UPDATE knex_migrations_lock SET is_locked = 0; then re-run. |
| Master migration is idempotent but tries to re-run | Missing row in knex_migrations | Add the row manually if the migration was applied out-of-band. |
Key Vault
| Symptom | Cause | Resolution |
|---|
Cannot find secret X from container app at startup | Managed identity missing role | Assign Key Vault Secrets User to the app's principal. |
403 Forbidden for your CLI session | RBAC propagation delay | Wait 1–2 min, retry. |
Secret is present but app reads undefined | Env-var name mismatch | Check the app's KV_SECRET_* env mapping in the container app config. |
Service Bus
| Symptom | Cause | Resolution |
|---|
| Worker doesn't pick up jobs | Wrong namespace name in app config | Match SERVICE_BUS_NAMESPACE env. |
Unauthorized from app to bus | Managed identity missing role | Azure Service Bus Data Receiver/Sender on the namespace. |
| Messages stuck in DLQ | Visible from Service Bus Explorer in the portal | See docs/operations/OPERATIONS_RUNBOOK.md §16 (pg-boss supervisor — note the platform uses both pg-boss for tenant jobs and Service Bus for cross-tenant events). |
DNS / TLS
| Symptom | Cause | Resolution |
|---|
| Cert renewal not happening | Custom-domain validation broken | Re-issue via Static Web App settings. |
*.rcm.medsuite.com returns 404 | Front Door wildcard route not configured | Recheck 1.6 step 4. |
api.rcm returns 502 intermittently | App Service cold-start during slot warmup | Set alwaysOn=true + at least one warmup instance for prod. |
Auth
| Symptom | Cause | Resolution |
|---|
Bootstrap script: duplicate key on email | Ran twice | Use --reset-password, or delete the row and rerun. |
| Login returns 401 with correct password | is_active = false | UPDATE security.platform_user SET is_active = true WHERE email = .... |
Login succeeds, but /platform/tenants returns 403 | Missing PLATFORM_ADMIN role assignment | Insert into security.platform_role_assignment. |
Where to look first
If you're truly stuck, escalate to engineering with: the failing endpoint URL, the
App Service slot + revision name, and the last 200 lines of logs.