Troubleshooting

Local Development

Cosmos DB Emulator connection fails

• Ensure Cosmos DB Emulator is running
• Check that the endpoint in api/local.settings.json matches the emulator (default: https://localhost:8081)
• Verify the emulator certificate is trusted
  • Windows: Emulator auto-installs certificate
  • Mac/Linux: Export and trust the certificate manually

Magic links not working

• Verify RESEND_API_KEY and FROM_EMAIL are configured for email delivery.
• Without RESEND_API_KEY, delivery is skipped and the API logs only masked recipient, subject, and sender information. The login link and verification code do not appear in logs or the normal API response.
• For automated local testing, use only the guarded E2E test mode described in the environment reference. It can return devLink and devCode only with the localhost and non-production safeguards active.

Frontend can't connect to API

• Verify API is running on http://localhost:7071
• Check vite.config.ts proxy configuration
• Ensure api/local.settings.json has correct CORS settings

Database containers not found

• Run setup script: cd api && npx ts-node scripts/setup-database.ts
• Verify all containers were created in Cosmos DB Emulator Data Explorer

Production Deployment

Static Web App deployment fails

• Verify GitHub Actions workflow has correct AZURE_STATIC_WEB_APPS_API_TOKEN secret
• Check that app_location, api_location, and output_location are correct
• Review GitHub Actions logs for build errors

API functions not responding

• Check Azure Function App logs in Azure Portal
• Verify environment variables are set in Function App Configuration
• Ensure Cosmos DB firewall allows Azure services

Authentication not working in production

• Verify FRONTEND_URL environment variable is set to your production domain
• Check that JWT_SECRET is set and secure
• Ensure RESEND_API_KEY and FROM_EMAIL are configured
• If a fresh link appears invalid or expired, request one new email and test the newest link or code once. Links and codes expire after 30 minutes and are one-time credentials.
• Don't paste a full link, code, email address, authorization header, or request body into logs, issues, or support messages.

Production monitoring

An alert fired

1. Open Azure Monitor → Alerts and review the affected time window.
2. Check Application Insights failures and recent requests for the same period.
3. Compare the start time with recent deployments or a burst of sign-in, order, invitation, or capacity activity.
4. Record only the operation, time range, severity, and sanitized failure category in an issue.

The baseline alerts don't send email or webhook notifications because they have no action groups.

Cosmos activity is missing from dependencies

Cosmos DB access that uses Azure Functions bindings may not appear as dependency telemetry. Use failed requests, Function traces, application failure events, and Cosmos DB metrics together. Don't treat an empty dependency view as proof that no database calls occurred.

The ingestion warning fired

• Check for retry loops, repeated failures, or temporary debug logging.
• Confirm ingestion is below the 0.1 GB/day cap after the cause is removed.
• Remember that the cap can make telemetry incomplete until it resets. Telemetry failures don't stop application workflows.

Rate Limiting

Getting 429 Too Many Requests

• Wait 15 minutes for rate limit to reset
• Rate limits: 5 requests per IP/email per 15 minutes
• Contact admin to adjust rate limits if needed

---

See also: Local Development · Azure Deployment · Environment Variables