Docker Mailserver UIDVALIDITY changed after a restore

After restoring Docker Mailserver, an IMAP client downloads every message again, shows old mail as new, loses local labels, or reports that the mailbox UIDVALIDITY changed. The server may still contain exactly one copy of every message. The disruption happens because the client can no longer trust its old mapping between cached records and server-side IMAP UIDs.

Do not respond by deleting the client account, clearing every Dovecot file, or editing UID numbers until you know which mailbox identity changed and why. First determine whether the complete pre-restore Maildir control state can be restored safely. If it cannot, accept one controlled client resynchronisation only after proving that server-side messages and flags are sound.

UIDVALIDITY is an identity boundary, not a message count. A changed value can trigger a full client resync without proving message loss or server-side duplication.

What UIDVALIDITY means

Each IMAP mailbox has a UIDVALIDITY value, and each message in that mailbox has a UID. Together with the mailbox name, those values let a client recognise a specific server message across sessions. The IMAP specification requires the server to change UIDVALIDITY when previous UID mappings no longer persist.

In Dovecot Maildir, dovecot-uidlist stores the mailbox UIDVALIDITY, next UID, global mailbox identifier, and the mapping between message UIDs and Maildir filenames. It is a control file, not a disposable index cache. Restoring only cur and new, or deleting the UID list after restore, can preserve message bodies while discarding their old IMAP identity.

1. Contain writes and capture evidence

If a restore has just gone live, pause mailbox-changing activity before more clients, deliveries, moves, or expunges create a second divergent state. Record the running image and the real persistent mounts:

docker inspect mailserver \
  --format 'image={{.Config.Image}} id={{.Image}}'

docker inspect mailserver \
  --format '{{range .Mounts}}{{println .Type .Source "->" .Destination .RW}}{{end}}'

docker compose exec mailserver dovecot --version
docker compose exec mailserver doveconf -n

Keep complete output private. Runtime configuration, account names, host paths, and mount sources can expose sensitive infrastructure. Confirm that /var/mail points at the intended restored mail-data storage and that the mailbox format is actually Maildir before using this guide.

2. Measure the affected mailbox identity

Query the problem account and compare the affected folder with an unaffected control folder:

docker compose exec mailserver \
  doveadm mailbox status -u [email protected] \
  'guid messages unseen uidnext uidvalidity' INBOX

docker compose exec mailserver \
  doveadm mailbox status -u [email protected] \
  'guid messages unseen uidnext uidvalidity' Archive

Replace the address and folder names privately. Compare these values with a pre-restore incident record, backup manifest, migration report, or the old server if it remains read-only. A current value by itself cannot prove that it changed.

Also capture a bounded Dovecot log window. Look for UIDVALIDITY changed, a broken or missing dovecot-uidlist, duplicate GUIDs, lock failures, read-only filesystems, permission errors, and capacity failures. The first error often explains the later client symptoms.

3. Prove message integrity separately

Do not use a client’s redownload count as the server’s message count. Check each affected mailbox through Dovecot, open a sample of old and recent messages, and compare with the protected source or backup inventory. Preserve evidence of:

• mailbox names and subscriptions;
• message counts and virtual sizes;
• old and recent message content;
• standard flags such as Seen, Answered, Flagged, Draft, and Deleted;
• custom keywords or labels;
• the current UIDVALIDITY, UIDNEXT, and mailbox GUID.

If actual messages are missing or duplicated, stop treating this as only a UIDVALIDITY incident. Protect both copies and investigate the restore, import, or synchronization path before letting clients mutate either side.

4. Find the restore boundary that changed

Docker Mailserver’s standard persistent layout separates mail storage, mail state, logs, and configuration. For Maildir identity, the critical question is whether the complete mail-data tree—including hidden and per-folder Dovecot control files—was restored consistently with the messages.

Common causes include:

• copying only cur and new while omitting dovecot-uidlist and dovecot-keywords;
• restoring messages from one timestamp and control files from another;
• starting Dovecot against an empty target before the restore completed;
• allowing delivery or IMAP writes on both old and new systems;
• using a generic file copy that did not preserve ownership, timestamps, hidden files, or atomic replacement;
• importing mail as new messages instead of synchronising mailbox identity;
• mounting the wrong mail-data directory after recreating the container.

Dovecot’s import documentation explicitly notes that doveadm import does not preserve UIDs. For a mailbox migration, Dovecot recommends its synchronization tooling and asks operators to verify flags, UIDs, UIDVALIDITY, and subscriptions.

5. Choose rollback or controlled resynchronisation

There are two valid recovery outcomes. Choose once, based on evidence.

Option A: restore the complete known-good mailbox state

This is appropriate when you have a consistent pre-incident backup or a read-only authoritative source containing the messages and matching control metadata, and no accepted new mail exists only on the changed target. Keep clients and delivery stopped, protect the current target, restore the complete mailbox state using the tested recovery method, and start the same pinned image.

Do not copy a lone old dovecot-uidlist over a mailbox whose messages have since changed. A stale UID list can map an old UID to the wrong message or omit accepted mail. Restore a consistent unit or use Dovecot’s supported synchronization path.

Option B: accept the new UIDVALIDITY

If the new server state is complete and authoritative but the old UID mapping cannot be recovered consistently, retain the new UIDVALIDITY. Verify the mailbox first, then reconnect one client and let it perform one full resync. Watch server I/O, network traffic, and client behaviour before releasing the rest.

A client may download bodies again, rebuild search indexes, or briefly show old mail as newly discovered. Do not reset UIDVALIDITY a second time to suppress that cost: another identity change causes another invalidation cycle.

6. For migrations, preserve identity deliberately

A file archive is useful for disaster recovery when it captures the complete persistent data consistently. A live migration is a different operation. Dovecot’s doveadm backup and doveadm sync use mailbox-aware synchronization and can preserve UID-to-GUID relationships when source and destination are configured correctly.

Test with a non-critical account first. Record source and destination message counts, flags, UIDVALIDITY, UIDNEXT, mailbox GUIDs, and subscriptions. Avoid opening target mailboxes before the first synchronization; Dovecot warns that doing so can create UIDVALIDITY or GUID conflicts. Keep the source authoritative and read-only during final cutover, then run the documented final synchronization for the chosen migration design.

Do not paste migration credentials into shell history or public notes. Use the authentication mechanism and protected configuration recommended for the pinned Dovecot versions.

7. Verify the chosen recovery end to end

Whether you restored old identity or accepted new identity, the acceptance test is broader than a successful container start:

1. Re-run mailbox status and record messages, unseen count, UIDNEXT, UIDVALIDITY, and GUID.
2. Open several old and recent messages through IMAP.
3. Confirm important flags, keywords, subscriptions, and folder hierarchy.
4. Deliver one controlled message and prove it appears exactly once.
5. Mark it read, flag it, move it, reconnect, and confirm state persists.
6. Reconnect one existing client and observe incremental sync or the expected one-time full sync.
7. Check an unaffected account or folder as a negative control.
8. Review logs for fresh UID, GUID, lock, permission, I/O, or capacity errors.
9. Recreate the mail container once and repeat the status plus delivery checks.

Retain the pre-recovery backup and evidence through the rollback window. If UIDVALIDITY changes again without another deliberate restore, investigate storage health and concurrent writers immediately.

Repairs to avoid

• Editing UIDVALIDITY by hand: a matching number does not make mismatched UID-to-message mappings valid.
• Copying only an old UID list: control state and message state must be consistent.
• Deleting every dovecot* file: control files, indexes, caches, subscriptions, and keyword maps have different consequences.
• Re-importing the same archive repeatedly: imports may create new messages rather than restore old identity.
• Resetting every client first: preserve server evidence before local caches obscure the original symptom.
• Accepting writes on both sides: split-brain mailbox state makes a clean rollback harder.
• Upgrading Docker Mailserver during recovery: keep image and configuration migration separate from identity repair.
• Assuming redownload means duplicates: prove server-side copies and UIDs independently.

Compact recovery order

1. Pause writes and capture the running image, Dovecot version, mounts, and effective mail configuration.
2. Record UIDVALIDITY, UIDNEXT, GUID, counts, and logs for affected and control mailboxes.
3. Prove server-side message, flag, keyword, and subscription integrity.
4. Identify whether the restore omitted, regenerated, or mismatched Maildir control state.
5. Protect the current target before any rollback.
6. Either restore one complete known-good state or accept one controlled client resynchronisation.
7. Verify mail access, delivery, flags, moves, reconnects, logs, and container recreation.
8. Keep the rollback set until identity remains stable under normal use.

Authoritative references: the IMAP specification’s UID rules explain why a server must signal invalidated mappings; Dovecot’s Maildir documentation defines dovecot-uidlist and warns that control files are not disposable indexes; its migration guide requires testing preservation of flags, UIDs, UIDVALIDITY, and subscriptions; and Docker Mailserver’s backup guidance identifies the persistent data that belongs in a recovery set. Match every command and migration design to the versions and storage layout you actually run.