Correcting KMail's "Dirty" Items

This problem is directly related to Akonadi bug #436550, which was reported in April, 2021. It results from the "dirty" items occasionally found by akonadictl fsck.

~ $ akonadictl fsck 2>&1 | grep ^Found
Found 5 external files.
Found 5 external parts.
Found no unreferenced external files.
Found 0 parts to be moved to external files
Found 0 parts to be moved to database
Found 6 collections without RID.
Found 0 items without RID.
Found 750 dirty items.

The "dirty" flag on an item in pimitemtable (one of the tables in the Akonadi database) is used to control certain aspects of asynchronous processing. It is set true when there are operations pending for a particular email message. Most of the time, the "dirty" flag is cleared one or two seconds later, when the once pending operation finishes up.

Occasionally, for reasons that are not entirely clear, the "dirty" flag can get set on dozens or even hundreds of messages all at once, as illustrated above. When this happens, the automatic clearing mechanism gets stuck, and is unable to repair itself automatically. The primary reason for a "dirty" item in this circumstance is that the field "remoteid" is not set correctly, making retrieval of a "dirty" message impossible in KMail. The message still exists on the disk. But KMail can't find it.

There ought to be a better way to correct this problem. If you think of a better way, please let the authors know about it, so this documentation can be improved. The following procedure will at least correct the database errors. But it does entail a lot of work.

  1. Exit KMail and stop the Akonadi server with a terminal command: akonadictl stop .

  2. Make a backup copy of all your email messages. You may be able to use PIM Data Exporter for this purpose. Or you may use Ark to make an archive, or Dolphin to make a second copy of ~/.local/share/local-mail/ somewhere else on your hard disk. If you're adventurous, you might just rename your local folders directory to something like local-mail-save . But it's safer to be sure you have a backup copy of your messages before you proceed.

  3. You should also make a backup copy of any filters you have created, and make sure you know how to restore any custom Sent mail folder, Drafts folder, or Templates folder entries associated with your KMail identities. The next step will remove all your personally customized mail folders, and you will need to patch some stuff up after Akonadi rebuilds its database tables.

  4. Now delete all the folders inside of the directory local-mail, or rename that directory to something like local-mail-save . Then start the KMail program. This will force Akonadi to erase all the database table entries associated with email messages. You will see your old folder names, briefly, but these will disappear when Akonadi finishes deleting all the "dirty" items (and all the clean ones, too).

  5. Exit KMail and stop the Akonadi server as explained in step 1, then restore the backup copy of your messages (created in step 2) to the ~/.local/share/local-mail/ directory.

  6. Start KMail up again, and force Akonadi to re-sync the database. The easiest way to do this is to FileCheck Mail (Ctrl+L); Akonadi automatically re-syncs all the folders when it fetches mail. This will take several minutes to complete, depending on how many messages you have saved in your KMail folders. But when the process is complete all the "dirty" items will be gone.

  7. Finally, you will want to restore your mail filter rules backed up in step 3, and check that all the custom folder items (Sent mail folder, etc.) for your identities are set the way you want them. You will also need to reset any custom folder properties you had set up, and you will probably have a bunch of spurious "Unread Message" notifications to deal with. But your Akonadi database tables will be all clean and shiny once again!