Troubleshooting

Common issues and their solutions.

Backend Returns 502

1. Check backend logs: docker logs monetra-backend --tail 30
2. Verify container is running: docker ps | grep backend
3. Common cause: failed Prisma migration — check _prisma_migrations table
4. Solution: Redeploy backend via Dokploy

Prisma Migration Fails / Backend Won't Start

Check migration status:

docker exec <db-container> psql -U monetra -d monetra \
  -c "SELECT migration_name, finished_at, rolled_back_at
      FROM _prisma_migrations ORDER BY started_at DESC LIMIT 5;"

Mark a failed migration as applied:

docker exec <db-container> psql -U monetra -d monetra \
  -c "UPDATE _prisma_migrations
      SET finished_at=NOW(), rolled_back_at=NULL, logs=NULL, applied_steps_count=1
      WHERE migration_name='MIGRATION_NAME';"

Fix checksum mismatch (after manual SQL changes):

docker exec <db-container> psql -U monetra -d monetra \
  -c "UPDATE _prisma_migrations
      SET checksum='CORRECT_HASH'
      WHERE migration_name='MIGRATION_NAME';"

Traefik Routes to Wrong Service

• Check Dokploy UI > Compose project > affected service > Domains tab
• Remove incorrect domain entries
• Note: Traefik v3 no longer supports Cookie() matcher — use traefik.enable=false for conflicting services

SSL Certificate Issues

Symptom	Cause	Solution
"TRAEFIK DEFAULT CERT" in browser	Traefik has no cert for the domain	Add domain in Dokploy with HTTPS enabled, or use Cloudflare Proxy
"NET::ERR_CERT_AUTHORITY_INVALID"	Self-signed cert visible to browser	Enable Cloudflare Proxy (orange cloud) + SSL mode "Full"
Mixed content warnings	HTTP assets loaded on HTTPS page	Ensure all asset URLs use relative paths or HTTPS

Connector Store Issues

Issue	Solution
/api/connectors returns 401	You need admin role — check your JWT token
Connector not showing after install	Refresh the page; check browser console for errors
Webhook URL not working	Verify the connector is enabled (not just installed)
"CORS error" on status page	Ensure /api/health has CORS headers (Access-Control-Allow-Origin: *)

Google Workspace "Not Connected"

• Error must return HTTP 400 (not 401) — code GOOGLE_NOT_CONNECTED
• HTTP 401 would trigger the Axios interceptor and logout the user
• If Google OAuth fails: check that the redirect URI in Google Cloud Console matches exactly

Rate Limiting

If you receive 429 Too Many Requests:

Endpoint	Limit	Reset
Login	10 req / 15 min	Per email address
Register	5 req / 60 min	Per IP
General API	300 req / 60 min	Per IP
Webhooks	30 req / 60 min	Per IP

Check the X-RateLimit-Reset header for the Unix timestamp when the limit resets.

Account Lockout

After too many failed login attempts:

Attempts	Lock Duration
5	5 minutes
10	10 minutes
15	15 minutes
20+	60 minutes

Wait for the lockout to expire, or reset via database if urgent.