Troubleshooting

Safe first checks for mail delivery, sign-in, TLS, imports and service failures.

Updated November 15, 2026 6 min read Maintained by Altgence

#Start with evidence

Troubleshoot the smallest failing surface first. Collect the exact symptom, the time in UTC, the affected mailbox or domain, and the relevant log lines. Do not restart the full stack, delete a queue or restore a backup until you have evidence that the action addresses the cause.

Useful read-only checks:

bash

systemctl --failed
systemctl status a8m-server a8m-admin alt8mail-control postfix dovecot nginx --no-pager
journalctl -u alt8mail-control --since '1 hour ago'
journalctl -u postfix --since '1 hour ago'
tail -n 100 /var/log/mail.log
postqueue -p
nginx -t
postfix check
doveconf -n
/opt/alt8mail/bin/alt8mail-control doctor

Treat queue deletion, mailbox deletion, retention runs, restores, package/release updates and service restarts as mutating operations. Get authorization and record what changed.

#Installation

Symptom	Likely cause	Safe first check
Installer stops during health checks	ClamAV can take time to load its first signatures	`tail -n 100 /var/log/a8m-install.log`; `systemctl status clamav-daemon`; `systemctl --failed`
Installer refuses the host	Not Debian 12 or the expected architecture	`cat /etc/os-release`; confirm the supported baseline in Requirements
Let's Encrypt fails	DNS, port 80, CAA or a proxy in front of the host	Check A records, port 80 reachability, `/var/log/letsencrypt/letsencrypt.log`, and `certbot renew --dry-run`
Certificate is self-signed after install	DNS was not ready at install time	Correct DNS and issue/assign a trusted certificate from System Control
Port 8808 is reachable from the internet	Installer firewall policy was not tightened	Restrict it at the provider firewall or VPN immediately
Mail is not listening	Provider blocks port 25 or Postfix is stopped	Check `ss -ltnp`, `systemctl status postfix`, provider firewall and `journalctl -u postfix`

Symptom	Likely cause	Safe first check
`/admin/` returns 404	Missing trailing slash or the admin service/nginx route is down	Try `/admin/`; `systemctl status a8m-admin`; `curl -fsS http://127.0.0.1:8081/api/health`; `nginx -t`
Admin sign-in rejects MFA	Admin console supports TOTP/recovery, not a passkey-only credential	Enrol an authenticator app or use a recovery code; do not disable MFA policy without approval
Session expires unexpectedly	Idle/absolute session limits or a password/admin reset	Review tenant session policy and recent admin audit events
System Control is unreachable	Wrong port, provider firewall, UFW or certificate warning	Use port 8808, not 88008; `curl -kfsS https://127.0.0.1:8808/healthz`; `systemctl status alt8mail-control`; `ss -ltnp`; `ufw status`
Control rejects a write	Missing CSRF or insufficient role	Refresh the page/session; confirm the permission for the action
SSO/OIDC fails	Provider unreachable, issuer/redirect mismatch, email/claim/domain/MFA evidence	Check the fixed `sso_error` code, provider discovery and `journalctl -u a8m-server`
SAML metadata returns 503	IdP metadata unreachable or invalid	Check IdP URL, SP certificate/key and server logs; restart clears the in-process replay cache

#Domains and DNS

Symptom	Likely cause	Safe first check
Domain verification fails	Missing/wrong ownership TXT, MX, SPF, DKIM `p=` mismatch or bad DMARC	Use the per-check detail in the admin domain drawer; query DNS with `dig`; wait for propagation
Outbound send is refused	Domain gate is not mail-ready	Complete ownership, MX, SPF, DKIM and DMARC verification
Inbound mail is absent	MX wrong, port 25 blocked, provider filtering	`dig MX`; `journalctl -u postfix`; `/var/log/mail.log`; test from another external provider
Outbound mail queues	Port 25 blocked, PTR/reputation, SPF/DKIM/DMARC or relay issue	`postqueue -p`; inspect the queue detail; check the relay and deliverability surfaces
`451 Temporary lookup failure` after an alias change	Stale Postfix lookup or virtual map issue	Inspect the alias lookup and Postfix logs; reload Postfix only after confirming the map
Mail client password rejected	Using the web password incorrectly, mail-client policy off, MFA mismatch or wrong port	Confirm full email address, IMAP/POP policy, IMAPS 993/submission 587, and app-password requirements for DAV

#Mail delivery and storage

Symptom	Likely cause	Safe first check
Queue grows	Upstream relay, DNS, recipient throttling or Postfix policy	Inspect queue age and deferral reason; do not flush a queue with thousands of old messages
Mailbox disk is full	Maildir/Cabinet growth, versions, retainers or quota guard	Check `df -h` and storage volumes; increase capacity before retrying uploads
Dovecot hibernation/socket errors	Socket permissions or master process state	`journalctl -u dovecot`; compare the deployed Dovecot configuration
Missing message after deletion	Legal hold, retention or a client-side action	Check hold state and audit; do not restore blindly over live data
Imported mail is missing folders	Source was POP3 or the job excluded folders	Check the fidelity report and source protocol
Import authentication fails	Full address, password/token, provider policy or expired OAuth	Validate source login again; use a fresh token or generic IMAP
Imported message is quarantined	ClamAV detected malware or scan failed	Review quarantine and logs; do not disable scanning

#Policy, DLP and licensing

Symptom	Likely cause	Safe first check
`409 LEGAL_HOLD` on deletion	A tenant or mailbox legal hold is active	Review Compliance → Holds; do not work around it
`422 DLP_BLOCKED`	A DLP block rule matched at send or delivery recheck	Review the rule and matched fields; edit the message or policy
`403 LICENSE_FEATURE`	A paid capability is not present or has expired	Check entitlements in Customer Admin/System Control; restart after updating the license if required
`403 WHITE_LABEL`	The white-label entitlement is missing	Verify the license feature set
`409 SEAT_LIMIT`	Active users exceed licensed seats	Review the seat meter; suspend or close accounts through the supported lifecycle
AI requests fail with budget/config errors	No provider configured or the monthly budget is exhausted	Review tenant AI configuration and usage; do not assume AI is free or unlimited
Office is not ready	Docker/agent unhealthy, JWT missing or public URLs invalid	Open System Control → Office and review readiness, services and logs

#Updates and restore

Symptom	Likely cause	Safe first check
Update fails before activation	Disk space, Git/deploy key, release asset or checksum	`tail /var/log/alt8mail-update.log`; `ls -lt /var/backups/alt8mail`; check free space
Update fails during health check	Migration, service or readiness failure	Let rollback finish; read the updater log and health checks; keep the backup directory
Rollback incomplete	Database restore failed	Use `scripts/alt8mail-recover-db.sh <backup-dir>` from the release tooling and preserve the logs
Restore is requested for one mailbox	Full restore is a disaster-recovery operation	Use mailbox/folder restore preview and additive `doveadm import`, never a full archive restore
Backup missing Maildirs	Maildirs were not selected	Create a new backup with Maildir message stores explicitly selected
Control backup is unencrypted	Panel archives are plain `.tar.gz`	Encrypt before off-host storage; protect and test the key

#When to escalate

Escalate when:

mail is not flowing in either direction after DNS and service checks;
a restore or update has failed or is partially applied;
a security control is bypassed or you suspect compromise;
the issue would require database surgery, direct queue deletion, retention changes or a manual secret rotation;
you need a capability whose entitlement is not active.

For the support process, see Support. For security issues, follow the repository security policy rather than publishing exploit details.

Need a hand?

We can help with the next step.

Talk to the team