Troubleshooting

Solutions to the most common issues encountered during setup and day-to-day use of Munera.

Cloud deployments

I'm not receiving email notifications

  1. 1Check your spam or junk folder for emails from noreply@munera.cloud
  2. 2In Munera, go to Profile → Notifications and verify email is enabled for the relevant event types
  3. 3If you previously unsubscribed, contact support@munera.cloud to re-enable your address

SSO login is failing

  1. 1Verify the ACS URL and Entity ID in your IdP exactly match the values in Settings → Security → SSO
  2. 2Check that the SAML attributes include an email field that matches the user's Munera account email
  3. 3Use the Test SSO button in Settings to see the raw SAML response and identify the failing attribute
  4. 4Ensure your IdP's metadata hasn't expired — if you uploaded an XML file, re-download and re-upload

Tasks are not syncing from Jira

  1. 1Go to Settings → Integrations → Jira and click Test Connection
  2. 2Verify your Jira API token hasn't expired (Jira tokens expire after 90 days by default)
  3. 3Check that the Munera webhook is registered in Jira: go to Jira → Settings → System → WebHooks and look for a webhook pointing to munera.cloud
  4. 4If the webhook is missing, disconnect and reconnect the integration to re-register it

Self-hosted deployments

Backend container won't start

# Check startup logs
docker compose logs backend | tail -50

# Common fixes:
# 1. Missing required environment variables
docker compose exec backend env | grep -E "SECRET_KEY|DATABASE_URL|REDIS_URL"

# 2. Database not reachable
docker compose logs postgres | tail -20

# 3. Redis not reachable
docker compose logs redis | tail -20

502 Bad Gateway from Nginx

# Check if the backend container is healthy
docker inspect munera-backend | grep -A5 Status

# Force restart
docker compose restart backend

# Check Nginx can reach the backend
docker exec munera-nginx curl -sf http://backend:8000/health

Migrations failing

# Check current migration state
docker compose run --rm backend alembic current

# If the DB is ahead (previous failed deploy)
docker compose run --rm backend alembic stamp head

# Retry
docker compose run --rm backend alembic upgrade head

Users cannot log in after a restart

If SECRET_KEY was changed or regenerated, all existing JWT tokens are immediately invalidated and users must log in again. Check your .env.production to ensure SECRET_KEY has not changed unexpectedly.

High memory usage

# Check per-container memory usage
docker stats --no-stream

# Limit PostgreSQL memory (add to docker-compose.yml postgres command)
command: postgres -c shared_buffers=256MB -c work_mem=4MB

# Limit Redis (add to docker-compose.yml redis command)
command: redis-server --maxmemory 512mb --maxmemory-policy allkeys-lru

Disk space running out

# Remove unused Docker data
docker system prune -f

# Prune old images (keep last 720 hours)
docker image prune -a --filter "until=720h" -f

# Check log sizes
du -sh /var/lib/docker/containers/*/

Collecting logs for support

# Collect all service logs
docker compose logs > munera-logs-$(date +%Y%m%d).txt

# Quick system check
docker compose exec backend python -c \
  "from app.config import get_settings; s=get_settings(); print(s.ENVIRONMENT)"

Attach the log file to your support ticket at support@munera.cloud. Enterprise customers can share logs directly in their dedicated support Slack channel.