Local Stack Does Not Start
- Confirm
.env exists or expected defaults are acceptable for local development.
- Run
docker compose config.
- Check whether ports
8080, 8001 to 8004, and 5173 are already occupied.
- Rebuild with
docker compose up --build.
Authentication Failures
- Missing bearer token: confirm the client sends
Authorization: Bearer ...
- Invalid bearer token: verify
JWT_SECRET_KEY alignment between issuer and consumers
- Distributor-only failure: confirm both
role and account_type claims are distributor
Invite Redemption Fails
- Confirm the invite has not expired or already been redeemed.
- Confirm the distributor alias matches the stored distributor username.
- Confirm trusted internal service credentials are configured for redemption handoff.
Game Session Problems
- Re-check invite status before attempting play.
- Use reconnect-token support when resuming a dropped session.
- Confirm the acting user matches the token subject before mutating game state.
Chat Problems
- Confirm the two users are entitled to communicate.
- Confirm moderator routes use moderator-role claims.
- If messages disappear from participant view, verify whether both participants have read them.
- If archives do not expire, check legal-hold state and the archive-expiry job.
Deployment Problems
- Confirm production secrets are present.
- Confirm migrations completed.
- Confirm health checks pass for authentication, WebSockets, and archive-expiry behavior.