Docker Mailserver Dovecot “mail_location not set and autodetection failed”

Dovecot accepts the login, then reports mail_location not set and autodetection failed, Mail storage autodetection failed, or an initialization failure for one mailbox. The tempting fix is to paste a mail_location line from an unrelated server. In Docker Mailserver, that can point Dovecot at the wrong tree while the real mail remains on the persistent /var/mail volume.

The safe fix is to trace four connected facts: the account returned by Dovecot’s user database, its expanded home and mail fields, the effective Dovecot configuration in the running container, and the volume actually mounted at the resolved path. Repair the first fact that is wrong; do not create a second empty mailbox hierarchy to silence the error.

A mail-location error is a path-resolution failure, not evidence that the mailbox is empty. Preserve the current mail volume before changing paths.

What the error actually means

Dovecot needs a mailbox driver and root path before it can open an account. If those values are not explicit, it may inspect known locations below the user’s mail home. Autodetection only succeeds when a recognised, populated mailbox layout exists. Dovecot deliberately does not create a missing mailbox while using autodetection.

Docker Mailserver normally supplies a coherent virtual-user and Maildir configuration. This error therefore often follows a stale custom Dovecot override, an incomplete migration, a missing or wrong /var/mail mount, an account lookup that expands to the wrong domain/user path, or a container image/configuration mismatch.

1. Capture the first failure and its scope

Reproduce one login while watching a bounded log window:

docker compose logs --since 10m --follow mailserver

Record whether the error affects one account, all accounts, only newly created accounts, or only one protocol. Preserve the first Dovecot error before follow-on IMAP messages. Keep raw logs private because they can contain addresses, mailbox names, client addresses, and host paths.

If the log instead begins with an authentication or TLS failure, start with the Docker Mailserver IMAP login guide. A successful password check followed by mail-storage initialization failure points further down the path.

2. Ask Dovecot how it resolves the user

Query an affected account and, if possible, one known-good account through the same running service:

docker compose exec mailserver \
  doveadm user [email protected]

docker compose exec mailserver \
  doveadm user [email protected]

Compare the returned home, UID, GID, and any mail-related fields. The exact output depends on the DMS and Dovecot versions. Do not assume that an address maps to /var/mail/example.com/person merely because that path looks plausible; use the effective userdb result and configuration.

If the account is missing or resolves differently from its peers, inspect the persistent DMS account configuration or external provisioner. Recreate an account only through the supported setup mechanism, and only after proving that doing so will not overwrite or orphan existing mail.

3. Inspect effective configuration, not a template

Dump the configuration loaded by the running container:

docker compose exec mailserver doveconf -n

docker compose exec mailserver sh -lc \
  'doveconf -n | grep -E "^(mail_|namespace|passdb|userdb)"'

Depending on the installed Dovecot major version, relevant settings may be represented by older mail_location syntax or newer fields such as mail_driver, mail_path, and mail_home. Match the documentation to the version inside the pinned image:

docker compose exec mailserver dovecot --version

Look for an empty or unexpected location, a path expanded from the wrong home, duplicate definitions, and custom namespaces. Also inspect the DMS-supported persistent extension file if you use one:

docker compose exec mailserver \
  sh -lc 'test -f /etc/dovecot/local.conf && cat /etc/dovecot/local.conf || true'

Configuration may contain private paths or backend details, so compare it locally rather than publishing the dump. Docker Mailserver documents docker-data/dms/config/dovecot.cf as the normal additive override copied into /etc/dovecot/local.conf. A whole-file override is broader and more likely to drift across image upgrades.

4. Prove the running image and mount

A correct Compose file is not proof that the current container uses it. Capture runtime identity and 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 \
  sh -lc 'findmnt /var/mail 2>/dev/null || mount | grep " /var/mail "'

The Docker Mailserver reference layout persists mail storage at /var/mail, configuration at /tmp/docker-mailserver, and optional runtime state at /var/mail-state. Confirm that the expected mail source is mounted read-write at the expected destination. Do not print the host source path in a public issue.

A newly created anonymous volume, an empty bind-mount source, or a mount moved to the wrong destination can make valid configuration look like failed autodetection. Stop at that point: locate and protect the original volume rather than populating the empty one.

5. Compare the resolved path with real mailbox evidence

Using the path derived from doveadm user and doveconf -n, inspect only the necessary levels inside the container. This placeholder must be replaced privately with the resolved path:

docker compose exec mailserver \
  sh -lc 'namei -l /var/mail/example.com/person'

docker compose exec mailserver \
  sh -lc 'find /var/mail/example.com/person -maxdepth 2 -type d -print'

For Maildir, expect the mailbox root and its cur, new, and tmp directories. Existing folders and messages are stronger evidence than a guessed path. If the real populated tree is elsewhere, determine whether the userdb/config is wrong or the wrong volume is mounted before moving anything.

If the path is correct but traversal fails, follow the Dovecot mailbox permission guide. Do not use recursive chmod 777 or broad chown; mail privacy and delivery processes depend on the intended numeric identity and restrictive modes.

6. Back up before changing location or mounts

Stop or quiesce writes, then preserve the mail-data volume, DMS configuration, current image reference, and Compose definition. For a bind-mounted reference layout:

docker compose down

# The archive contains private mail; store it securely.
sudo tar --numeric-owner -cpf \
  mail-data-before-location-repair.tar \
  -C ./docker-data/dms mail-data

tar -tf mail-data-before-location-repair.tar >/dev/null

For a named volume, use a documented volume backup or storage snapshot rather than guessing its host path. Test that the protected copy contains the affected Maildir and metadata. The broader backup and restore runbook covers mail, state, configuration, image pinning, and isolated restore checks.

7. Apply the smallest durable repair

The evidence normally leads to one of these repairs:

• Wrong or empty mail volume: restore the original mount mapping or selected named volume, without copying empty data over it.
• Stale custom override: remove or correct only the conflicting setting in the persisted DMS override, then validate configuration.
• Broken user mapping: repair the account or userdb source so its home and mail fields match the established layout.
• Missing Maildir for a genuinely new account: fix explicit location/provisioning so supported delivery creates it; do not hand-build a path that disagrees with DMS.
• Permissions or host policy: repair the narrow failed traversal or write boundary while retaining the intended ownership and restrictive access.

Validate before starting service:

docker compose run --rm mailserver doveconf -n >/dev/null

docker compose up -d mailserver

If the one-off command is unsuitable for your Compose version or service dependencies, validate inside a controlled replacement container before cutover. Do not combine this recovery with a Docker Mailserver image upgrade; path repair and version migration should be separate changes.

8. Verify storage, IMAP, and delivery

A clean startup is necessary but not sufficient. Prove the repaired account through Dovecot and through the client-visible path:

docker compose exec mailserver \
  doveadm user [email protected]

docker compose exec mailserver \
  doveadm mailbox list -u [email protected]

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

docker compose logs --since 10m mailserver

1. Open the account over IMAP and confirm the expected folders and old messages.
2. Deliver one controlled message and confirm it appears once.
3. Mark it read, move it to a test folder, reconnect, and confirm state persists.
4. Verify an unaffected account still works as a negative control.
5. Recreate the mail container once and repeat user lookup, folder listing, and delivery.
6. Check that logs contain no fresh autodetection, permission, or index errors.

If the path now resolves but Dovecot reports a corrupted index, keep the location repair intact and use the separate scoped index recovery guide. Do not move mail again to treat a derived index problem.

Repairs to avoid

• Pasting a generic mail_location: it may hide the error by exposing a new empty mailbox.
• Deleting the mail-data volume: this removes the evidence and may remove the mail itself.
• Moving mail before resolving the user: a wrong lookup will simply point away from the new location too.
• Creating cur/new/tmp everywhere: it makes autodetection succeed without proving that delivery and existing mail use that tree.
• Recursive chmod 777 or blind ownership changes: they weaken mailbox privacy and can break other services.
• Editing only inside the container: the change disappears on recreation.
• Overriding an entire Dovecot config for one setting: copied files drift as the image evolves.
• Upgrading during recovery: it combines path, syntax, default, and image changes in one incident.

Compact diagnosis order

1. Capture the exact account, first Dovecot error, and affected scope.
2. Compare doveadm user output for affected and healthy accounts.
3. Record the installed Dovecot version and effective doveconf -n.
4. Inspect the running image and live /var/mail mount.
5. Compare the resolved path with the populated mailbox tree.
6. Protect mail and configuration before changing anything.
7. Repair one mount, override, mapping, provisioning, or permission boundary.
8. Verify old mail, new delivery, IMAP state, an unaffected account, logs, and recreation.

Authoritative references: Docker Mailserver’s optional configuration guide identifies the persistent mail, state, log, and configuration volumes; its Dovecot override guide documents dovecot.cf, local.conf, effective configuration debugging, and version-matched setup tooling. Dovecot’s mail-location documentation explains explicit drivers and paths, mailbox-root autodetection, and why autodetection does not create a missing mailbox. Use the documentation matching the Dovecot major inside your pinned DMS image.