Mailu Docker Compose Errors: Fixes

The Problem

Mailu containers fail to start, crash during operation, or produce errors in Docker Compose logs. This covers the most common issues and their fixes.

Quick Diagnostic

# Check all container statuses
docker compose -p mailu ps

# Check for recent errors
docker compose -p mailu logs --tail 50 2>&1 | grep -i "error\|fatal\|failed"

# Check which containers are unhealthy or restarting
docker compose -p mailu ps | grep -v "Up"

Fix 1: Port 25 Already in Use

Error: bind: address already in use for port 25.

Cause: Another process (usually Postfix installed on the host) is already listening on port 25.

# Find what's using port 25
sudo ss -tlnp | grep :25

Fix:

# If it's the host Postfix:
sudo systemctl stop postfix
sudo systemctl disable postfix

# If it's another mail container:
docker ps | grep -i mail
docker stop <container_name>

Then restart Mailu:

docker compose -p mailu up -d

Fix 2: Front Container Keeps Restarting

Error: The mailu-front (Nginx) container enters a restart loop.

Check logs:

docker compose -p mailu logs front --tail 100

Common causes:

TLS Certificate Not Found

nginx: [emerg] cannot load certificate "/certs/cert.pem"

Mailu generates certificates on first start. If the cert volume is empty or permissions are wrong:

# Check the certs volume
docker compose -p mailu exec front ls -la /certs/

# If empty, restart the certdumper or admin container
docker compose -p mailu restart admin

For Let’s Encrypt, verify your domain resolves to the server and ports 80/443 are accessible.

Resolver Configuration

nginx: [emerg] host not found in resolver

The front container can’t resolve internal container hostnames. Check that all backend containers are running:

docker compose -p mailu ps

If containers like imap, smtp, or admin are down, start them first — front depends on them.

Fix 3: Admin Container Won’t Start

Error: mailu-admin container exits immediately or loops.

Check:

docker compose -p mailu logs admin --tail 100

Database Migration Failed

sqlalchemy.exc.OperationalError: database is locked

The SQLite database is corrupted or locked. Fix:

# Stop all containers
docker compose -p mailu down

# Check the database
docker run --rm -v mailu_data:/data alpine \
  sqlite3 /data/main.db "PRAGMA integrity_check"

# If corrupted, export and reimport
docker run --rm -v mailu_data:/data alpine sh -c \
  'sqlite3 /data/main.db .dump > /data/main.sql && \
   mv /data/main.db /data/main.db.bak && \
   sqlite3 /data/main.db < /data/main.sql'

# Restart
docker compose -p mailu up -d

SECRET_KEY Not Set

Mailu requires a SECRET_KEY in mailu.env. If it’s missing or empty:

# Generate a random key
python3 -c "import secrets; print(secrets.token_hex(16))"

# Add to mailu.env
SECRET_KEY=<generated_key>

Fix 4: IMAP/SMTP Authentication Failures

Error: Email clients can’t authenticate. Logs show authentication failed errors.

Check Dovecot logs:

docker compose -p mailu logs imap --tail 100

Wrong Password

Verify the password works in the admin UI:

1. Go to https://mail.yourdomain.com/admin
2. Navigate to your domain → users
3. Reset the password and try again

IMAP Container Not Ready

If the IMAP container is still initializing, authentication fails. Wait 30-60 seconds after starting all containers before attempting login.

Incorrect Client Settings

Use these settings in your email client:

Setting	IMAP	SMTP
Server	mail.yourdomain.com	mail.yourdomain.com
Port	993	465 or 587
Security	SSL/TLS	SSL/TLS or STARTTLS
Username	Full email address	Full email address

Fix 5: DNS Resolution Failures Inside Containers

Error: Containers can’t resolve external hostnames. Logs show DNS-related errors.

Cause: Docker’s internal DNS or the host’s DNS configuration is interfering.

# Test DNS from inside a container
docker compose -p mailu exec admin nslookup google.com

Fix: Add a DNS resolver to your mailu.env or Docker daemon configuration:

# In mailu.env
SUBNET=192.168.203.0/24

If using systemd-resolved on the host (Ubuntu 22.04+), the DNS stub listener on 127.0.0.53 can conflict with Docker. See Docker DNS Resolution Not Working for the full fix.

Fix 6: Fetchmail/Webmail Not Working

Error: Fetchmail (external account fetching) or webmail (Roundcube/Snappymail) errors.

Fetchmail Container Crash

docker compose -p mailu logs fetchmail --tail 50

Fetchmail often fails if external mail servers require specific TLS versions. Check the external server settings and ensure fetchmail can reach ports 993/995.

Webmail Shows “Connection Refused”

The webmail container can’t reach the IMAP backend. Verify:

# Check if IMAP container is up
docker compose -p mailu ps | grep imap

# Check internal connectivity
docker compose -p mailu exec webmail ping imap -c 2

If IMAP is down, restart it:

docker compose -p mailu restart imap

Fix 7: Disk Space Issues

Error: Containers crash with write errors or No space left on device.

df -h /var/lib/docker
du -sh /var/lib/docker/volumes/mailu_*

Fix:

# Clean up Docker system
docker system prune -a --volumes

# Check which volumes are largest
docker system df -v | grep mailu

# If mail storage is full, check user quotas in admin UI

Fix 8: Outdated Docker Compose Format

Error: docker compose can’t parse the docker-compose.yml file.

Mailu generates its own docker-compose.yml via the setup wizard. If you’re upgrading from an older Mailu version, the Compose format may be outdated.

Fix: Regenerate the Compose file from the Mailu setup wizard with your current settings. Keep your mailu.env — it contains all your configuration.

Prevention

• Pin Mailu to a specific version — don’t use :latest. Check the Mailu GitHub releases for the current stable version.
• Monitor with Uptime Kuma — TCP checks on ports 25, 465, 587, 993
• Back up regularly — especially the mailu_data volume containing the database and user data
• Check logs weekly — docker compose -p mailu logs --since 7d 2>&1 | grep -i error
• Keep Docker updated — some Mailu issues are Docker version-specific

Related

• How to Self-Host Mailu
• Mailu vs mailcow
• Email Deliverability: SPF, DKIM, DMARC
• Self-Hosted Email Going to Spam: Fixes
• Best Self-Hosted Email Servers