+++
date = '2025-05-18T11:34:09+02:00'
draft = false
title = 'Dovecot Index Cache Issues'

[cover]
image = "/imgs/dove.jpg"
alt = "Bunch of Doves on a roof"
caption = ""

+++

# Understanding `dovecot.index.cache`

I recently migrated an old mail server system into its new home. After the migration, I checked the logs and noticed some warnings that looked like this:
```
May 17 11:23:13 server1 dovecot: dsync-local(user@domain.tld)<cRjZCwGnKWiIvicA2dm5Tw>: Error: Mailbox INBOX: mmap(size=511310568) failed with file /var/vmail/domain.tld/user/Maildir/dovecot.index.cache: Cannot allocate memory
```
The error indicates that the `dovecot.index.cache` file is too big to process, and Dovecot cannot allocate enough memory to handle it. 

# What Are `dovecot.index.cache` Files?

Dovecot, the most popular IMAP server, uses a set of index files (`dovecot.index`, `dovecot.index.cache`, `dovecot.index.log`, etc.) to speed up mailbox access. The file I had to deal with stores cached message metadata (headers, flags, and preview text) so Dovecot does not have to read each message file in the mailbox every time.

Over time, the `dovecot.index.cache` file can grow very large or become outdated. Here are a few reasons why this happens:

### During Normal Operation

- Deleted or moved messages may leave behind unused metadata.
- Corrupt or unreferenced entries might accumulate if a process is interrupted.
- Stale data can hang around for years if not explicitly purged.

### After a Migration

Migrations are particularly prone to creating out-of-sync or bloated index files because:

- **File timestamps and UIDs change**: Dovecot's cache is based on assumptions about message state. A migration (e.g. via `rsync` or `imapsync`) may change those assumptions, causing the cache to mismatch the actual message data.
- **Index format/version mismatch**: If you switch Dovecot versions between servers, the format of `.index.cache` might be incompatible or inefficient.
- **Partial cache rebuilds**: After a migration, Dovecot may try to reuse old cache files that no longer reflect the real contents of the mailbox, leading to odd behavior or performance issues.

# How to Deal with These Files

After migrating to the new servers, I encountered a few of these messages in the log, so I had to search through and find all users affected by this. Since these large files not only consume unnecessary disk space but also affect performance and cause `dsync` issues, I had to do something about it.

## Is It Safe to Delete These Files?

Short answer: **Yes** — it's safe to delete all `dovecot.index*` files inside a user's Maildir.

Dovecot will automatically regenerate the indexes when needed. This will result in a small delay the first time a user accesses their mailbox after deleting these files, but performance will return to normal quickly.

## How to Find and Clean Up Large Index Files

First, you should check what "large" means for your setup. I checked for files that are larger than 100 MB in size using the following command:
```bash
find /var/vmail -type f -name "dovecot.index.cache" -size +100M -exec ls -lh {} \;
```
After validating these files and users, I then moved into the user’s Maildir and removed the files:
```
cd /var/vmail/domain.tld/affecteduser/Maildir/
rm dovecot.index*
```
## What Else Can I Do?

There’s another way to deal with large index files: you could increase the virtual memory limit that Dovecot is allowed to use, which is controlled by the `default_vsz_limit` in Dovecot’s configuration files. 

Another option to prevent future bloat of these files would be adjusting the `mail_cache_fields` and `mail_never_cache_fields` in the configuration.

I decided to delete these files for affected users because these files had grown so large before migrating to the new setup. After regenerating, the files are much smaller, and time will tell if this becomes an issue again.

# Conclusion

If you encounter these warnings in your logs, it's worth checking the `dovecot.index.cache` files and dealing with them. Cleaning them up is safe and easy — Dovecot will take care of rebuilding what it needs.

