1.8 Phase 1 Troubleshooting

Quick reference for common bootstrap-time failures. The full operations runbook (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.

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.

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 `OPERATIONS_RUNBOOK.md` §16 (pg-boss supervisor — note the platform uses both pg-boss for tenant jobs and Service Bus for cross-tenant events).

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	Container app cold-start	Set min replicas ≥ 1 for prod.

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`.

If you're truly stuck, escalate to engineering with: the failing endpoint URL, the Container App revision ID, and the last 200 lines of logs.