Repair a Broken Dovecot Mailbox with doveadm force-resync

One user's mailbox has stopped behaving, and Dovecot cannot fix it on its own, so doveadm force-resync is the repair tool. This guide runs it against one named user and mailbox in 10 to 20 minutes, then shows you how to check the result.

It follows the installed dovecot-core package, version 1:2.3.21+dfsg1-2ubuntu6.5, and its Dovecot 2.3 manpage. You need shell access to the mail host, the doveadm command, and enough permission to use Dovecot's administrative socket. Allow more time if you need a backup or a second check.

1. Confirm the installed command

Check which binary will run and record the package version before touching a mailbox:

$ command -v doveadm
/usr/bin/doveadm
$ dpkg-query -W -f='${Package} ${Version}\n' dovecot-core
dovecot-core 1:2.3.21+dfsg1-2ubuntu6.5

The installed manual describes doveadm force-resync as a repair command for cases where Dovecot cannot solve mailbox problems automatically. For sdbox and mdbox storage it also checks the storage files. It is not a general-purpose index rebuild, and it is not a harmless status query.

2. Choose one exact mailbox

Start with one user and one mailbox. The documented example uses the Inbox:

$ sudo doveadm force-resync -u '[email protected]' INBOX

• Use the exact user. Replace [email protected] with the user known to Dovecot. The -u option also accepts a mask with * and ?, but do not use a wildcard while you are still diagnosing one broken account.
• INBOX is a real name. It is not a placeholder. Substitute another name such as Archive only when that is the mailbox that needs repair.
• sudo is optional. It is shown because mailbox administration commonly needs elevated access, but the syntax does not require it. Use the least privilege your Dovecot configuration permits. If your operator account can already reach the administrative socket, omit it.

The command may print nothing useful on success. Check the exit status immediately:

$ status=$?
$ printf 'force-resync exit status: %s\n' "$status"
force-resync exit status: 0

A zero status means the command completed successfully. It does not mean the mailbox had no earlier damage, and it does not replace an application-level check such as opening the mailbox through IMAP.

3. Protect the repair window

force-resync attempts to fix mailbox problems and can update mailbox storage. Before running it on a valuable account, confirm that no migration, restore, mail delivery repair or concurrent mailbox conversion is in progress. Keep the original backup and any incident evidence until the user has verified the result.

4. Add diagnostics only when needed

Use -v for verbosity and a progress counter:

$ sudo doveadm -v force-resync -u '[email protected]' INBOX

Use -D when you need debug messages while investigating a failure:

$ sudo doveadm -Dv force-resync -u '[email protected]' INBOX

These options report more detail. They do not change the target mailbox or make an invalid user valid. Capture the output in your incident record, but check it does not expose mailbox names or other operational data before sharing it outside the mail team.

If the command cannot connect to the expected Dovecot administrative socket, -S can select one explicitly. Its argument is either an absolute local UNIX socket path or a remote hostname:port:

$ sudo doveadm -S /path/to/doveadm.socket force-resync -u '[email protected]' INBOX
$ sudo doveadm -S mail-admin.example.org:12345 force-resync -u '[email protected]' INBOX

5. Repair a controlled list of users

Once the single-user command is understood, -F can read one username per line from a file:

$ umask 077
$ printf '%s\n' '[email protected]' '[email protected]' > /tmp/dovecot-resync-users
$ sudo doveadm force-resync -F /tmp/dovecot-resync-users INBOX
$ rm -- /tmp/dovecot-resync-users

Review the file before running the repair. It holds account names, so the restrictive umask and prompt removal matter. If the command fails, keep a copy of the exact input list in your incident records instead of rebuilding a bigger list from memory.

$ sudo doveadm force-resync -A INBOX

Use this only as an intentional fleet operation, with a maintenance plan, monitoring and a tested recovery route. A targeted -F list is easier to review and stop.

6. Diagnose a failed repair

First preserve the exit status and the diagnostic output. Then check the user, mailbox spelling, Dovecot configuration and socket access. A useful configuration snapshot is:

$ sudo doveconf -n

Compare the configured user database, mailbox location and storage driver with the account you targeted. The Dovecot manpage recommends including this output when reporting a bug to the Dovecot mailing list.

If a repair fails because the service is busy, coordinate with the mail service owner before stopping anything. Restarting Dovecot or editing storage files is outside this command and can create a second failure. If the mailbox is still inaccessible after a zero status, test the account through the normal client path and inspect Dovecot's service logs before repeating the repair.