<\!DOCTYPE html> Common Issues and Solutions
Back to Documentation

Common Issues and Solutions

This guide covers the most common issues users encounter with Mail-Rulez and their solutions.

Quick Links

Installation Issues

Container Fails to Start

Symptoms:

  • Container exits immediately after starting
  • Status shows "Exited" or "Restarting"

Common Causes & Solutions:

  1. Port Conflict

    # Check if port 5001 is in use
netstat -tlnp | grep 5001

# Solution: Change port in docker-compose.yml
ports:
  - "5002:5001"  # Use different external port

  2. Missing Environment Variables

    # Check container logs
docker logs mail-rulez

# Solution: Ensure all required env vars are set
docker run -e FLASK_ENV=production \
           -e MASTER_KEY=$(openssl rand -hex 32) \
           mail-rulez:latest

  3. Volume Permission Issues

    # Fix permissions
docker exec mail-rulez chown -R app:app /app/data

Health Check Failures

Symptoms:

  • Container marked as "unhealthy"
  • Automatic restarts

Solution:

# Test health endpoint manually
docker exec mail-rulez curl -f http://localhost:5001/health

# Adjust health check timing in docker-compose.yml
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:5001/health"]
  interval: 60s  # Increase interval
  timeout: 10s   # Increase timeout
  retries: 5     # More retries

Connection Problems

IMAP Authentication Failures

Symptoms:

  • "Authentication failed" errors
  • Cannot connect to email server

Common Solutions:

  1. Gmail/Google Workspace

    • Enable 2-factor authentication
    • Generate app-specific password
    • Use app password instead of regular password
    • Enable "Less secure app access" (if not using app passwords)

  2. Outlook/Office 365

    • Ensure IMAP is enabled in account settings
    • Use OAuth2 if available
    • Check for conditional access policies

  3. Generic IMAP Issues

    # Verify settings manually
Server: imap.gmail.com
Port: 993
Security: SSL/TLS
Username: full email address
Password: app-specific password

SSL Certificate Errors

Symptoms:

  • SSL verification failures
  • Certificate trust issues

Solutions:

# For self-signed certificates (testing only)
# Add to account configuration:
"verify_ssl": false

# For corporate certificates
# Mount certificate bundle:
docker run -v /path/to/ca-bundle.crt:/etc/ssl/certs/ca-bundle.crt ...

Email Processing Issues

Emails Not Being Processed

Symptoms:

  • Emails remain in inbox
  • Processing appears stuck

Troubleshooting Steps:

  1. Check Service Status

    • Navigate to Dashboard
    • Verify processing service shows "Running"
    • Check last processing time

  2. Review Logs

    # Check processing logs
docker exec mail-rulez tail -f /app/logs/email_processing.log

# Look for errors
grep ERROR /app/logs/email_processing.log

  3. Verify Rules

    • Ensure rules are active (not disabled)
    • Check rule conditions match emails
    • Test rules with sample emails

Duplicate Processing

Symptoms:

  • Same email processed multiple times
  • Duplicate entries in folders

Solution:

# Clear processing cache
docker exec mail-rulez rm -f /app/data/processing_cache.db

# Restart processing service
# Navigate to Services → Email Processor → Restart

Performance Problems

Slow Processing

Symptoms:

  • Long delays between email batches
  • High CPU/memory usage

Solutions:

  1. Adjust Batch Size

    # In Services configuration
"batch_size": 50  # Reduce from default 100
"processing_interval": 300  # Increase interval (seconds)

  2. Optimize Rules

    • Avoid complex regex in high-volume rules
    • Order rules by frequency (most common first)
    • Consolidate similar rules

  3. Resource Limits

    # docker-compose.yml
services:
  mail-rulez:
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 2G

Memory Leaks

Symptoms:

  • Increasing memory usage over time
  • Container restarts due to OOM

Solution:

# Enable automatic restart
docker update --restart=always mail-rulez

# Monitor memory usage
docker stats mail-rulez

# Set memory limits with swap
--memory=1g --memory-swap=2g

Retention Issues

Emails Not Being Deleted

Symptoms:

  • Retention policies not executing
  • Trash folders growing indefinitely

Common Causes:

  1. Scheduler Not Running

    • Check Dashboard → Retention Scheduler status
    • Verify scheduler is enabled in configuration

  2. Policy Configuration

    # Verify policy settings
- Check retention days > 0
- Ensure folders are correctly specified
- Verify policies are active

  3. IMAP Permissions

    • Some servers restrict deletion
    • Check account has delete permissions
    • Verify trash folder exists

Accidental Deletion Recovery

Steps to Recover:

  1. Check trash folders immediately
  2. Use IMAP client to restore
  3. Disable retention policy temporarily
  4. Review audit logs for deletion records

Docker Issues

Network Problems

Symptoms:

  • Cannot access web interface
  • Connection refused errors

Solutions:

  1. Bridge Network Issues

    # Use host networking (development only)
docker run --network=host ...

# Or create custom network
docker network create mail-rulez-net
docker run --network=mail-rulez-net ...

  2. Firewall Rules

    # Allow Docker through firewall
sudo ufw allow 5001/tcp

Storage Issues

Symptoms:

  • "No space left on device"
  • Cannot save configuration

Solutions:

# Check disk usage
docker system df

# Clean up unused resources
docker system prune -a

# Move Docker root directory
# Edit /etc/docker/daemon.json
{
  "data-root": "/new/docker/root"
}

Getting Help

If your issue isn't covered here:

  1. Check Logs

    • Application logs: /app/logs/
    • Container logs: docker logs mail-rulez
    • System logs: Dashboard → Logs

  2. Gather Information

    • Mail-Rulez version
    • Docker version
    • Error messages
    • Steps to reproduce

  3. Contact Support

Related Documentation