Troubleshooting

Solutions to common MailCade issues.

#Server Won't Start

#Port Already in Use

**Symptoms**: Server shows "Stopped", error about port in use

**Check what's using the port**:

# macOS/Linux
lsof -i :1025
 
# Windows
netstat -ano | findstr :1025

**Solutions**:

Kill the process using the port
Or change MailCade's SMTP port:
- Settings → Server Configuration
- Change SMTP Port to 1026 or another
- Click Restart Server

#Permission Denied

**Symptoms**: Server fails with permission error

**Cause**: Ports below 1024 require admin/root

**Solution**: Use port 1025 or higher (recommended anyway)

#Emails Not Appearing

#Server Not Running

Check sidebar:

Email Server ● Running  ✅

If stopped:

Click gear icon ⚙️
Click Start Server

#Wrong Configuration

Verify your app sends to:

Host: localhost (or 127.0.0.1)
Port: 1025

**Common mistakes**:

TLS/SSL enabled (should be disabled)
Authentication enabled (should be none)
Wrong port number
Wrong host

#Test with cURL

Isolate the issue:

curl -v smtp://localhost:1025 \
  --mail-from [email protected] \
  --mail-rcpt [email protected] \
  --upload-file - <<EOF
Subject: Test
 
If you see this, MailCade works!
EOF

If this works but your app doesn't, the problem is in your app's configuration.

#WebSocket Issues

#Real-time Updates Not Working

**Symptoms**: Need to refresh to see new emails

**Causes**:

WebSocket connection failed
Firewall blocking WebSocket
API port mismatch

**Solutions**:

Restart MailCade

Check API port is accessible:

curl http://localhost:8025/api/v1/messages

Check firewall settings

#Performance Issues

#Slow Inbox

**Cause**: Too many emails

**Solution**:

Settings → Server Configuration
Lower Email Retention to 100-200
Old emails auto-delete
Inbox speeds up

#High CPU/Memory

**Cause**: Rapidly sending thousands of emails

**Solutions**:

Slow down email sending rate
Lower email retention
Restart MailCade periodically
Close and reopen app

#Installation Issues

#macOS: "App is Damaged"

**Error**: "MailCade is damaged and can't be opened"

**Solution**:

xattr -cr /Applications/MailCade.app

Then try launching again.

#macOS: Security Warning

**Error**: "Can't open because from unidentified developer"

**Solution**:

System Settings → Privacy & Security
Scroll to "MailCade was blocked"
Click "Open Anyway"
Launch MailCade again

#Windows: SmartScreen Warning

**Solution**:

Click "More info"
Click "Run anyway"

(App isn't code-signed yet, hence the warning)

#Linux: AppImage Won't Run

**Make it executable**:

chmod +x MailCade-*.AppImage
./MailCade-*.AppImage

**FUSE errors**:

./MailCade-*.AppImage --appimage-extract
./squashfs-root/mailcade

#UI Issues

#Dark Mode Not Working

Check system dark mode is enabled
Restart MailCade
Or manually set: Settings → General → Theme → Dark

#Window Too Small/Large

Resize window to preferred size. Size is saved automatically.

To reset:

Quit MailCade
Relaunch
Resize as needed

#Text Cut Off

**Try**:

Zoom reset: Cmd/Ctrl + 0
Restart MailCade
Update to latest version

#Update Issues

#Update Check Fails

**Symptoms**: "Failed to check for updates"

**Causes**:

No internet
GitHub API rate limit
Firewall

**Solutions**:

Check internet connection
Wait and try again
Manually download from releases page

#Update Won't Install

Quit MailCade completely
Download new version manually
Install over old version
Launch

#Docker/Container Issues

#Can't Connect from Docker

Your app in Docker can't use localhost. Use:

**macOS/Windows**:

environment:
  MAIL_HOST: host.docker.internal

**Linux**:

extra_hosts:
  - "host.docker.internal:host-gateway"
environment:
  MAIL_HOST: host.docker.internal

#Platform-Specific

#macOS: Icon Missing in Dock

killall Dock

#Windows: Tray Icon Missing

Settings → Personalization → Taskbar → Ensure MailCade is allowed

#Linux: Font Rendering Issues

# Ubuntu/Debian
sudo apt install fonts-liberation
 
# Fedora
sudo dnf install liberation-fonts

Then restart MailCade.

#Getting Logs

Logs help diagnose issues:

**macOS**:

~/Library/Logs/MailCade/

**Windows**:

%APPDATA%\MailCade\logs\

**Linux**:

~/.config/MailCade/logs/

Check main.log for errors.

#Still Stuck?

#Before Reporting

Check logs for errors
Try with curl (isolate issue)
Restart MailCade
Update to latest version
Check existing GitHub issues

#Report Issue

Open an issue with:

✅ OS and version
✅ MailCade version
✅ Error messages
✅ Steps to reproduce
✅ Logs (if applicable)

#Common "Not a Bug" Issues

**"MailCade doesn't actually send emails"**
→ Correct. MailCade catches emails locally for testing.

**"Can't access from another computer"**
→ By design. MailCade is for local development only.

**"No SPF/DKIM headers"**
→ MailCade tests content/functionality, not email authentication.

#Prevention Tips

Keep MailCade updated
Use reasonable email retention (500 or less)
Clean inbox regularly
Use curl to test connectivity
Plan different ports for different projects

#What's Next?

Settings - Customize MailCade
Contributing - Help improve MailCade