cPanel + Dovecot: `doveadm exit code 68` - diagnosis and definitive fix

cPanel + Dovecot: doveadm exit code 68 - Diagnosis and Definitive Fix#

During routine server administration, especially post-migration or after backup restores that bypass the Dovecot Indexer, it's common to find inconsistencies in email disk usage in cPanel (Jupiter). The symptom in the panel is usually generic: quotas that don't load, frozen screens, or incomplete mailbox readings.

When you drop to the CLI, the real error appears:

doveadm: Error: cmd mailbox status: Mailbox [email protected]: Failed to lookup mailbox status: Mailbox doesn't exist
"/usr/bin/doveadm" reported error code "68"

This isn't a "random bug." It's a structural mismatch between the logical mailbox metadata and the physical Maildir structure on disk.

The phantom quota loop#

On cPanel servers, the panel runs automated Perl scripts (such as generate_maildirsize or rebuildmaildir) to query mailbox disk usage. This Perl script interacts with the filesystem via calls like getdents() to scan directories under the mail path. Then, the wrapper executes Dovecot commands (doveadm quota recalc or doveadm mailbox status).

If a mailbox is orphaned or corrupted (e.g., it exists logically in cPanel configuration files like passwd but has no physical folder on disk, or vice versa), the doveadm execution crashes with exit code 67 (User doesn't exist) or exit code 68 (Mailbox doesn't exist). Because doveadm fails with an error status code, the Perl wrapper aborts or enters an infinite loop while iterating accounts, leading to a general quota display failure in the interface:

2) Disk consistency verification#

First objective validation:

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

A valid Maildir must contain the following directories:

• cur/
• new/
• tmp/

If one of these is missing, Dovecot returns exit code 68 during status/index operations because it cannot locate the physical inbox path.

Physical quota (VFS) vs. logical quota (dovecot/zlib)#

In production environments, understanding the architectural difference between quota systems is critical:

• Physical Quota (VFS/Filesystem): The physical space occupied by file blocks on disk, queried via du -sh or Unix filesystem quotas.
• Logical Quota (Dovecot/Zlib): The logical size calculated by Dovecot from the maildirsize cache file. If the Dovecot zlib compression plugin is enabled, messages are stored compressed on disk. The physical disk usage will be lower than the logical quota. The zlib plugin maps physical compressed size vs. logical uncompressed size in separate metadata fields (such as ,S=) in the dovecot-uidlist file.

If the maildirsize cache file is corrupted, Dovecot will show drastic deviations compared to physical VFS disk usage.

Complementary confirmation test:#

Attempting to create a mailbox and receiving an "already exists" error (because Dovecot still sees it logically in dovecot-uidlist) while physical directories do not exist under the Maildir path is a strong indicator of logical-physical inconsistency.

I also validate the status directly:

doveadm mailbox status -u [email protected] messages INBOX

If it fails with "Mailbox doesn't exist" but the account is in the panel, the zombie state is confirmed.

3) Architectural deep dive: syscalls, maildirsize, and ftruncate#

To rebuild the logical quota cache consistently, we must understand the system calls invoked when the Dovecot daemon handles recalculations and mailboxes:

1. getdents(): Invoked by the operating system and cPanel wrappers to iterate through directory entries and index message files (cur, new, tmp).
2. truncate() / ftruncate(): When we run a quota recalculation via doveadm quota recalc or when Dovecot processes incoming mail, the maildirsize quota cache is updated. Dovecot opens the file and calls ftruncate to resize it before writing the new list of message sizes and quota limits. If Dovecot experiences high I/O wait times or is interrupted during the ftruncate call, the maildirsize cache may end up truncated to 0 bytes or corrupted, causing phantom quotas in the panel.

Verifying Dovecot's virtual authentication maps in userdomains and the domain passwd configurations in passwd (where cPanel matches accounts to system UID/GID) is vital to ensure that Dovecot can resolve the user during queries.

4) Bulk correction & recovery commands#

On servers with many email accounts, individual manual corrections are highly inefficient. We use cPanel's internal utilities and Dovecot commands to perform bulk reconstruction of Maildir structures and recalculate quotas:

4.1 rebuilding maildirs and sincronizing cPanel#

To reconstruct the missing folders (cur, new, tmp) for all users under a domain at once, run cPanel's native rebuild script:

/scripts/rebuildmaildir --force domain.com

4.2 recalculating quotas via cPanel and Dovecot#

If the maildirsize file is corrupted or out of date, force its regeneration by calling the cPanel utility for the specific user:

/scripts/generate_maildirsize --confirm cpanel_user

Then, run a logical quota recalculation directly in Dovecot for the target account:

doveadm quota recalc -u [email protected]

4.3 global Dovecot reindexing#

To reindex all mailboxes on the server and align physical changes with logical indexes:

doveadm index -A '*'

Critical detail: Enclosing the '*' in single quotes is mandatory in bash to prevent the shell from expanding the wildcard into current directory paths.

4.4 sample audit post-operation#

Verify that Dovecot returns a success status for the recovered accounts:

doveadm mailbox status -u [email protected] messages INBOX
doveadm mailbox status -u [email protected] messages INBOX

5) Prevention, monitoring, and orphaned accounts#

To prevent future technical debt from zombie mailboxes and ensure all active panel users have valid logical quotas, we implement proactive monitoring routines.

Run the following pipeline to scan all mailboxes and print accounts returning user or mailbox lookup errors:

doveadm user '*' | xargs -I{} doveadm quota get -u {} 2>&1 | grep -E "doesn't exist|Error"

Alternatively, to audit general outputs or filter out specific user lookup failures to focus on successful responses or other quota statuses:

doveadm user '*' | xargs -I{} doveadm quota get -u {} 2>&1 | grep -v "doesn't exist"

If the output of the first command lists any accounts, they are orphaned (configured in the cPanel database but lacking indexing integrity or physical Maildirs). Apply the recovery workflow (rebuildmaildir and quota recalc) to these accounts before users experience Webmail accessibility issues.

6) Post-migration playbook to avoid technical debt#

Every email migration requires active validation. This is the standardized playbook I follow:

1. rsync finished -> run rebuild:

    /scripts/rebuildmaildir --force domain.com

1. Regenerate cPanel quota files:

    /scripts/generate_maildirsize --confirm cpanel_user

1. Services stabilized -> reindex and recalculate quotas:

    doveadm index -A '*'
    doveadm quota recalc -u [email protected]

1. Validate critical accounts:

    doveadm mailbox status -u [email protected] messages INBOX

1. Confirm disk usage in the panel and test Webmail access.
2. Record evidence in the migration change log (commands + timestamp + result).

Production takeaways#

doveadm exit code 68 is a structural integrity signal. Ignoring it leads to a cascade effect: inconsistent quotas, Webmail errors, and loss of client trust. When you fix the root cause (Maildir structure + indexing), the environment stabilizes. Mature infrastructure doesn't just "restart the service"; it validates structure, rebuilds with method, and leaves technical evidence of what was done.

See also

Servers From VestaCP to cPanel: fixing the Roundcube IMAP mailbox corruption error

Infrastructure Anatomy of a phantom email: filesystem and Dovecot IMAP desynchronization

Servers The anatomy of a troubleshooting: ghost quotas, Dovecot, and the illusion of physical disk space on cPanel

This post is licensed under CC BY-NC.