Zimbra: Common Issues and How to Fix Them

Introduction¶

Zimbra bundles Postfix, an LDAP directory, a Java mailbox store (mailboxd), Jetty, OpenLDAP, and more behind the zmcontrol wrapper. When something breaks, the trick is knowing which component failed and which zm* command inspects it. Everything below runs as the zimbra user unless noted.

First moves for any incident¶

su - zimbra
zmcontrol status          # which services are up/down
df -h                     # /opt/zimbra full? this causes most "random" failures
zmcontrol -v              # version, for matching KB articles
tail -f /var/log/zimbra.log /opt/zimbra/log/mailbox.log

zmcontrol status is the dashboard. A Stopped line points you straight at the component.

mailboxd won't start¶

Symptoms: webmail shows "service unavailable", zmcontrol status lists mailbox as Stopped, IMAP/POP refused.

zmmailboxdctl status
zmmailboxdctl start
tail -100 /opt/zimbra/log/mailbox.log        # the actual Java stack trace
tail -50  /opt/zimbra/log/zmmailboxd.out

Common causes:

• Disk full on /opt/zimbra — free space (see below), then start.
• Port 8080/7071 already bound — ss -ltnp | grep -E '8080|7071'; a previous JVM didn't die. zmmailboxdctl stop, confirm no java process for the zimbra user, start.
• Corrupt Lucene index — stack trace mentions CorruptIndexException. Reindex the affected mailbox from the admin console, or: zmprov reIndexMailbox [email protected] start.
• JVM heap too small after adding users — zmlocalconfig -e mailboxd_java_heap_size=4096 then restart. Rule of thumb: 25–30% of RAM, leave room for LDAP + Postfix + OS.

Expired SSL certificate¶

The self-signed Zimbra CA is valid for a fixed period; commercial certs expire too. Symptoms: browsers reject webmail, zmcontrol status may show services flapping, proxy logs show handshake failures.

# What's installed and when does it expire?
zmcertmgr viewdeployedcrt all

# Self-signed: regenerate the whole chain (CA + services), then restart
zmcertmgr createca -new
zmcertmgr deploycrt self -new
zmcontrol restart

# Commercial cert: place the files, verify the chain, deploy
#   /opt/zimbra/ssl/zimbra/commercial/commercial.key   (your private key)
#   commercial.crt (leaf), commercial_ca.crt (intermediates + root, in order)
zmcertmgr verifycrt comm commercial.key commercial.crt commercial_ca.crt
zmcertmgr deploycrt comm commercial.crt commercial_ca.crt
zmcontrol restart

Gotcha: verifycrt fails if commercial_ca.crt has the intermediates in the wrong order or is missing the root. Build it leaf-last: intermediate(s) then root, concatenated. Check expiry across the fleet with the SSL Certificate Checker after deploy.

If LDAP itself uses an expired cert, zmcontrol restart can hang — start LDAP alone first: ldap start, then zmcertmgr steps, then the rest.

Mail queue backing up¶

zmcontrol status                 # is MTA/amavis/opendkim up?
mailq | tail -1                  # queue size
postqueue -p | grep -c '^[A-F0-9]'
qshape deferred | head           # WHERE is it stuck (by domain)

• All deferred to one domain — that MX is down or greylisting; usually self-resolves. Force a retry: postqueue -f.
• Everything deferred, amavis timeouts in the log — amavisd/ClamAV is dead or OOM. zmamavisdctl restart; check freshclam isn't wedged holding the DB.
• Queue full of bounces / spam from one account — compromised mailbox. Change the password, then delete their queued mail: zmqueue -q <domain> delete is not a thing — use postsuper -d ALL only after filtering, or delete by sender: mailq | awk '/compromised@/{print $1}' | tr -d '*!' | postsuper -d -.
• opendkim failing — DKIM signing key missing after a domain change: zmdkimkeyutil -q -d example.com shows the key; -a adds one.

LDAP is down¶

Nearly everything depends on it.

ldap status
ldap start
tail -50 /opt/zimbra/log/zmconfigd.log
/opt/zimbra/common/libexec/slapd -h ... # don't run by hand; use ldap start

# Test a bind
zmlocalconfig -s zimbra_ldap_password        # the admin bind password
ldapsearch -x -H ldap://localhost:389 -D "uid=zimbra,cn=admins,cn=zimbra" \
  -w "$(zmlocalconfig -s -m nokey zimbra_ldap_password)" -b "" -s base

• ldap_bind: Invalid credentials — zimbra_ldap_password in localconfig drifted from what's in the directory. On the LDAP master, reset with zmldappasswd.
• Replica won't sync — clock skew between master and replica (fix NTP), or the replication agreement's credentials changed. zmreplchk reports status.
• mdb_env_open / "environment mapsize" errors — the LDAP MDB database hit its size cap. Raise ldap_db_maxsize via zmlocalconfig -e and restart LDAP.

Disk full on /opt/zimbra¶

du -xh --max-depth=2 /opt/zimbra | sort -h | tail -20

Usual culprits and safe cleanups:

• /opt/zimbra/log/ — old mailbox.log.*, zmmailboxd.out. logrotate should handle these; if not, delete rotated ones. See logrotate configuration.
• /opt/zimbra/data/amavisd/tmp/ and quarantine/ — stale scan temp files and old quarantined mail. Safe to clear the tmp dir.
• /opt/zimbra/redolog/ — do not delete active redologs; if huge, mailboxd isn't archiving them (it's probably down).
• /opt/zimbra/backup/ — old backup sessions. Trim with zmbackup retention settings, not rm, on Network Edition.
• Core dumps (core.*, hs_err_pid*.log) in /opt/zimbra — delete after saving one for analysis.

Free ~1 GB, then zmcontrol start.

Verification and troubleshooting¶

zmcontrol status                       # all services Running
zmprov gs $(zmhostname) | grep -i status
# End-to-end: send yourself a message and watch it traverse
echo test | mail -s "zimbra check $(date +%s)" [email protected]
tail -f /var/log/zimbra.log            # queued -> delivered

• zmcontrol start returns but services die seconds later — check /opt/zimbra/log/ for the component that flaps; almost always disk, cert, or LDAP.
• Webmail loads but sending fails "451 4.3.0" — MTA can't reach LDAP or amavis; zmmtactl restart.
• Admin console 404 / won't load, webmail fine — the admin app runs on 7071; proxy or cert issue specific to that port.
• Everything green but users report slowness — heap pressure or GC pauses; zmstat-chart / the zmstat CSVs under /opt/zimbra/zmstat/ show JVM and IO.
• After an OS yum update — a new glibc/openssl can break the bundled binaries; Zimbra ships its own libs under /opt/zimbra/common/lib, but kernel and systemd changes still bite. Match the OS to Zimbra's support matrix.

Related tools and reading¶

• On-site: SSL Certificate Checker, Email Deliverability Test, DNS MX Lookup, Blacklist Checker.
• Related posts: SPF, DKIM and DMARC end to end, Postfix as a null client.