Gotchas

A curated subset of the deployment gotchas catalog. The full, numbered list (G1–G31) with exact fixes lives in DEPLOYMENT-GUIDE.md — this page is the "read before you touch prod" shortlist.

Deploy mechanics

• G16 — image tags must be LITERAL in docker-compose.yml. dstack does not expand ${IMAGE_TAG}; a variable tag means it silently won't re-pull. Bump the literal tag every deploy.
• dstack ignores compose ${:-default} defaults — flags like CONCLAVE_INPERSON_VIA_CAPTURE must be set explicitly, or they read as false (this silently disabled the DiariZen post-pass).
• Never re-provision a CVM — it wipes the sealed volume. Deploy in place by --cvm-id.

In-person WebSockets

• G17 — the Phala gateway kills long-lived WS at ~2–4 min (close code 1006). The fix is the Option-A TLS-passthrough ingress (wss://capture.conclavehq.org → in-CVM HAProxy, TIMEOUT_*=3600s) plus client reconnect. See Deployment.
• On macOS the Docker VM drops long WS too — run diart natively for local in-person testing; Linux CVMs are unaffected.

Diarization / ASR chain

• G24–G26 — the post-pass didn't fire because the enqueue flag was false, the GPU worker was on a stale URL, and reconcile no-op'd when VFTE found no voiceprints. All three had to be fixed together for the authoritative pass to run end to end.
• ASR — force language=en + temperature=0 on NEAR Whisper (auto-detect garbles English); whisper-1 404s → use openai/whisper-large-v3.

Auth (open)

• G27–G31 — web login loop. Google sign-in reaches the dashboard then bounces to /login (both apps), worse on sign-out → sign-in. A cluster of Vercel-rewrite bugs; several fixes shipped (Bearer token, client-set cookie, no-store) but it still reproduces (G31). Tracked at Conclave#13; currently the top blocker for web sign-in. See Status.

Source: DEPLOYMENT-GUIDE.md (G1–G31), task-plan/MASTER-TASK-LIST.md.