Operations

Troubleshooting

Common issues and their solutions.

Common Issues

Problem	Solution
Server won't start	Check logs: `docker compose -f docker-compose.prod.yml logs api`. Usually a missing env var or database connection issue.
License activation fails	Ensure your server can reach the internet. Check `docker compose -f docker-compose.prod.yml logs api \| grep license`
Emails going to spam	Ensure SPF/DKIM/DMARC are configured. Warm up mailboxes for 2–3 weeks before campaigns.
Campaign not sending	Check: status is "active", current time is within send window, mailboxes are assigned, leads have next_send_at set.
Warmup not working	Requires active license. Check coordinator connectivity: worker logs should show "[Warmup] Got X tasks"
SMTP test fails	Verify host/port/credentials. Try TLS port 587 or SSL port 465. Check if the provider requires an app password.
IMAP sync not pulling replies	Check IMAP credentials are correct and port 993 is used. Check worker logs for "[IMAP]" errors.
AI features not working	Check API key in Settings → AI. Use "Test Connection" to verify. Check daily token cap isn't exhausted.
API returns 403	License may be revoked or expired. Check `/health` endpoint and license status in admin panel.

Checking Logs

bash

cd /opt/cleanmails

# All services
docker compose -f docker-compose.prod.yml logs -f

# API server only
docker compose -f docker-compose.prod.yml logs -f api

# Worker only (campaigns, warmup, IMAP, validation)
docker compose -f docker-compose.prod.yml logs -f worker

# Last 100 lines from API
docker compose -f docker-compose.prod.yml logs --tail=100 api

# PostgreSQL logs
docker compose -f docker-compose.prod.yml logs postgres

Health Check

bash

# Basic health (checks DB connectivity)
curl http://localhost:8080/health

# Expected response:
# {"status":"ok"}

# If unhealthy:
# {"status":"error","detail":"db connection lost"}

Service Status

bash

cd /opt/cleanmails
docker compose -f docker-compose.prod.yml ps

# Expected: all services should show "healthy" or "running"
# If a service is "restarting", check its logs

Database Issues

Check PostgreSQL connectivity

bash

# Test from host
docker compose -f docker-compose.prod.yml exec postgres pg_isready -U cleanmails

# Connect to database
docker compose -f docker-compose.prod.yml exec postgres psql -U cleanmails cleanmails

Restore from backup

bash

cd /opt/cleanmails

# Stop app (keep postgres running)
docker compose -f docker-compose.prod.yml stop api worker frontend

# Restore
gunzip -c backups/cleanmails_backup_TIMESTAMP.sql.gz | \
  docker compose -f docker-compose.prod.yml exec -T postgres psql -U cleanmails cleanmails

# Restart
docker compose -f docker-compose.prod.yml up -d

Redis Issues

bash

# Check Redis is responding
docker compose -f docker-compose.prod.yml exec redis redis-cli ping
# Expected: PONG

# Check queue sizes
docker compose -f docker-compose.prod.yml exec redis redis-cli info clients

Email Deliverability Issues

Check DNS records

bash

# SPF
dig TXT yourdomain.com

# DKIM
dig TXT default._domainkey.yourdomain.com

# DMARC
dig TXT _dmarc.yourdomain.com

# MX
dig MX yourdomain.com

Check IP blacklists

Visit MXToolbox Blacklist Check and enter your server IP.

Resetting Admin Password

If you've lost your admin password, reset it directly in PostgreSQL:

bash

cd /opt/cleanmails

# Generate a bcrypt hash (use an online tool or:)
docker compose -f docker-compose.prod.yml exec api sh -c \
  'echo "UPDATE users SET password_hash=crypt(\'NewPassword123\', gen_salt(\'bf\')) WHERE email=\'admin@example.com\';" | psql -U cleanmails cleanmails'

# Or connect directly and update
docker compose -f docker-compose.prod.yml exec postgres psql -U cleanmails cleanmails

# Then restart to clear any cached sessions
docker compose -f docker-compose.prod.yml restart api

Force Restart All Services

bash

cd /opt/cleanmails
docker compose -f docker-compose.prod.yml down
docker compose -f docker-compose.prod.yml up -d

Getting Help

Check the Support page for direct assistance
Include your logs and health check output when reporting issues
Mention your server OS, RAM, and Docker version