Skip to main content

Troubleshooting

Common deployment and runtime issues, in order of how often they actually happen.

"Session Expired" in Teams (clock skew)​

Symptom: User opens the Ticku tab in Teams and immediately sees a "Session Expired" modal.

Cause: The user's PC clock is behind real time. Teams issues a JWT whose nbf (not-before) timestamp appears to be in the future, so validation fails.

Fix: Sync the machine clock. On Windows:

Start-Service w32time
w32tm /resync

Check skew first whenever a single user reports auth failures while others are fine.

Teams Tab Shows Login Prompt Instead of Silent SSO​

  • Verify webApplicationInfo in the manifest matches the Azure app registration (client ID + Application ID URI).
  • Verify the Teams client IDs are added as authorized client applications on the Expose-an-API blade.
  • Grant admin consent in Entra ID → Enterprise applications.

Email-to-Ticket Stopped Working​

Start with the worker: the whole feature is driven by a 2-minute email cycle that calls /api/cron/email.

  1. The cycle isn't running — if neither CRON_SECRET nor GRAPH_WEBHOOK_SECRET is set, the worker skips the job and logs a warning. Nothing renews and nothing polls. Look for [email-cycle] in the worker logs; a 401 there means the worker's secret disagrees with the web app's.
  2. Mail permissions missing (403) — the graph_app mode needs Mail.ReadWrite + Mail.Send application permissions with admin consent on the platform SSO app. Without them every app-only call fails. See Azure App Registration.
  3. IMAP against Microsoft 365 — imap_basic cannot work there; Microsoft retired basic auth for IMAP and SMTP AUTH. Switch the inbox to imap_oauth.
  4. Delegated token revoked — a password change or revoked consent invalidates the refresh token. Reconnect the mailbox.
  5. Graph subscription lapsed — push subscriptions expire and must renew; the email cycle renews them, so this usually reduces to cause 1.
  6. APP_URL not reachable — for push mode, Graph must be able to POST to your webhook endpoint over public HTTPS.
  7. Circuit breaker open — after 5 consecutive failures the inbox trips (circuitOpen) and that tenant's admins are notified. Fix the underlying error, then re-enable from Admin → Email.

For mail that arrives but produces no ticket — filtered, threaded, duplicated, or routed elsewhere — work through Email Health & Troubleshooting instead; that's an application-level question, not a deployment one.

Admin Lists Are Empty / Wrong Tenant's Data​

Symptom: A user who belongs to multiple tenants sees empty lists, or data from the wrong organization.

Cause: The active tenant didn't resolve as expected — the ticku_tenant cookie or /t/{slug} didn't match a usable membership, so context fell back to another tenant.

Fix: Use the tenant switcher to select the intended tenant. Confirm the user has an ACTIVE membership in it and that the tenant itself is ACTIVE (not suspended). See Multi-Tenancy.

Container Won't Start / Unhealthy​

docker compose logs app --tail 100
  • Most startup failures are missing or malformed env vars — compare against Environment Variables.
  • EMAIL_ENCRYPTION_KEY must be exactly 64 hex characters.
  • Confirm DATABASE_URL is reachable from inside the container network.

Migrations Fail​

  • Confirm the database user has DDL privileges.
  • If migration history is out of sync with the actual schema, do not force-reset in production — contact the development team.

Notifications Not Arriving​

  • Email: verify SMTP credentials; check app logs for send errors (v1.0 does not retry failed sends).
  • Teams: the recipient must have signed in via Teams/Microsoft at least once.