cPanel + Dovecot: `doveadm exit code 68` — Root Cause and Definitive Fix

After account migrations, cPanel email disk usage pages may fail to load or show inconsistent quota behavior. The CLI usually exposes the real issue:

doveadm: Error: cmd mailbox status: Mailbox INBOX.user@domain.com: Failed to lookup mailbox status: Mailbox doesn't exist
"/usr/bin/doveadm" reported error code "68"

This is typically not a software bug. It is a logical/physical mismatch between Dovecot mailbox metadata and the on-disk Maildir structure.

1) Zombie mailbox state

The mailbox exists logically in namespace/account metadata, but required Maildir folders are missing or inaccessible.

Common root causes:

partial migration (account metadata moved, mailbox data not fully copied);
selective restore (configs restored without raw mailbox data);
broken ownership/permissions on mailbox directories.

2) Consistency verification

ls -la /home/cpanel_user/mail/domain.com/mailbox/

Valid Maildir requires:

cur/
new/
tmp/

Missing folders usually lead to doveadm status/index failures.

Validate directly:

doveadm mailbox status -u user@domain.com messages INBOX

3) Surgical fix for isolated accounts

cd /home/user/mail/domain.com/mailbox/
mkdir -p cur new tmp
chown -R user:mail .
chmod -R 700 .

doveadm force-resync -u user@domain.com INBOX
doveadm index -u user@domain.com INBOX

4) Enterprise fix for many domains

/scripts/rebuildmaildir --force domain.com
doveadm index -A '*'

Keep '*' quoted to avoid shell-side expansion.

5) Syntax trap: `-A` vs `-u`

Do not combine global and user-specific scopes:

wrong: doveadm index -A -u user@domain.com
correct: use either -A or -u, depending on scope.

6) Post-migration playbook

rsync completed -> /scripts/rebuildmaildir --force domain.com
Services stable -> doveadm index -A '*'
Validate critical users with doveadm mailbox status ...
Confirm cPanel disk usage and webmail behavior
Record command evidence in migration change logs

Conclusion

doveadm exit code 68 is a structural integrity signal. Treat Maildir with database-grade rigor. Fixing the root cause (directory structure + indexing) restores stability and prevents recurring incidents.

This post is licensed under CC BY-NC.