# &kmail; Troubleshooting

## Introduction to &akonadi;

&kmail; has been under active development since 1997. A lot of bugs have cropped up over the years. Many of these have been resolved. If you are curious about any of those old bugs, please see the KMail/FAQs Hints and Tips in the &kde; UserBase Wiki. Or visit &kde;'s main bug tracking page to learn about bugs of a more recent vintage.

At the present time (2021), many of the problems people are experiencing with &kmail; involve the &akonadi; server. &akonadi; is an auxiliary program that functions as an intermediary between &kmail; (plus all the other &PIM; applications) and a general purpose database daemon (most commonly "mysqld"). It also facilitates inter-process communications among the various pieces of the &PIM; applications. Depending on the way your system is configured, &akonadi; may be started during the bootup / login process. Or it may not start until you invoke a &PIM; application program (like &kmail;, or &kaddressbook;, or &kontact;).

There are two application programs that permit one to interact with the &akonadi; server directly: `akonadictl` (a terminal-oriented control program), and `akonadiconsole` (a GUI application). Here is a little information about those two programs.

### The Akonadictl Control Program

&akonadi; status report &akonadi; status report

Akonadictl Status Report, 32 Agents Running

The preceding screenshot illustrates one of the commands one may use with the `akonadictl` program. Here are all the commands `akonadictl` recognizes.

    ~$ akonadictl start

Starts the &akonadi; server.

    ~$ akonadictl stop

Stops the &akonadi; server.

    ~$ akonadictl restart

Stops the &akonadi; server, then launches it anew.

    ~$ akonadictl status

Produces the status report illustrated in the preceding screenshot.

    ~$ akonadictl instances

Lists the &akonadi; server instances (more than one can be running at the same time).

    ~$ akonadictl vacuum

Cleans up &akonadi;'s storage, or at least tries to do that.

    ~$ akonadictl fsck

Performs a file consistency check. The output from this command can be quite voluminous, especially if you have added your own folders to &kmail;. Use this version of the command (piping the output through grep) to verify that your &akonadi; database is healthy, without producing a lot of extraneous output.

    ~ $ akonadictl fsck 2>&1 | grep ^Found
    Found 0 external files.
    Found 0 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 0 dirty items.

RID stands for RemoteId, a named field in the mysql database tables. If there are more than 0 items without RID, you have a minor problem that should be corrected. If there are more than 0 dirty items you may have a major problem that must be corrected. See "Unable to Fetch Item ..." and also Correcting &kmail;'s "Dirty" Items, below.

### The Akonadiconsole Program

What akonadiconsole looks like What akonadiconsole looks like

Akonadiconsole in action

The `akonadiconsole` program provides twelve different "windows" into the inner workings of the &PIM; applications. Here is a brief summary of the available views.

Agents tab.

- Here you can see a list of the user agents (processors).

Browse tab.

- This tab provides an overview of the various collections of data &akonadi; is maintaining, organized as a hierarchical tree that shows how many items reside in each collection.

Debugger tab.

- Here you can turn debugging on and off, and view the debug message log.

Logging tab.

- This tab lets you view messages emitted by various &akonadi; components.

DB Browser tab.

- Use this tab to peek inside the mysql database. There are many different tables.

DB Console tab.

- Here you can query the mysql database.

Query Debugger tab.

- Use this tab to turn database query debugging on and off. &kmail; queries the mysql database many times in just a few seconds; output can be voluminous.

Job Tracker tab.

- The &PIM; applications perform various functions by initiating "jobs". Use this tab to toggle job tracking on and off.

Resources Schedulers tab.

- Here you can see which resources are needed when a particular &PIM; function is invoked. You can see a list of all the &akonadi; resources in your system in the `~/.config/akonadi/` directory.

Notification Monitor tab.

- Use this tab to monitor notifications sent by various &akonadi; resources.

Item Search tab.

- This tab provides a generic search function. Searches can be restricted to Calendar, Contact, Email, or Note.

Monitors tab.

- Here you can see a list of all the monitors running under &akonadi;, and also view their properties. Agents, resources, and even some application programs are monitored.

## "Unable to Fetch Item from Backend" When Entering &IMAP; Folder

There are at least two possible reasons for this. Here are some workarounds.

Workaround 1

- - edit `~/.local/share/akonadi/mysql.conf`

  - Under the [mysql] section, add: `binlog_format=row`

  If this does not work, try workaround 2 (below).

Workaround 2

- This one is a matter of restarting so &kmail; can fetch those pesky items. Some possible steps include:

  Use &Alt;F2 (&krunner;) or &konsole; to type ``kquitapp kmail`` , then wait a minute, then ``akonadictl stop`` . Wait a minute, type ``akonadictl start`` , wait a minute, then type ``kmail`` . This stops &kmail; (closing all windows), stops the &kmail; backend, restarts the &kmail; backend, and restarts &kmail;. Having a working internet connection increases the chances of success. Sometimes, you can also just do ``kquitapp kmail`` , wait a minute, and then start &kmail; again. Often, a few restarts seem to be needed. It is unclear what causes this error, but on bad network connections it is more likely to happen.

See also the next topic to learn how akonadiconsole can be helpful.

## Your Emails Are Not Being Sent, Without Error Messages

If &kmail; does not send mail without saying anything, the agent responsible for dispatching messages may be stuck. Of course, you should first verify you have proper network connectivity so mail can be sent!

To remedy this, it might help to abort the current action and restart it. First, quit &kmail; by using &krunner; (&Alt;F2) or &konsole; and typing: ``kquitapp kmail`` . Note that a normal &Alt;F4 or File Quit does not do the trick! Wait a minute, then start &kmail; again. Now start akonadiconsole using &krunner; (&Alt;F2) or &konsole;. Go to the Mail Dispatcher Agent (under the Agents tab), do a right-click, and abort the current action. You will most likely get some error messages popping up. Now go back to &kmail; and choose File Send Queued Messages. Now it might work. If not, instead of aborting the current action, try toggling the offline/online status of the Mail Dispatcher Agent (same context menu) or restarting things as mentioned in workaround 2 of the previous topic.

akonadiconsole can be quite helpful for a number of situations because it shows all the agents, the separate components of the &kmail; backend. You can stop and start them, put them in offline mode, abort ongoing actions &etc;. It can be very helpful when &kmail; is acting cranky.

Sometimes the Mail Dispatcher Agent fails to function because the dbus daemon (a system-level facility for inter-process communications) is not functioning correctly. Your best bet in this circumstance is simply to reboot the system. The dbus daemon is one of the first processes started when you log in to the &kde; desktop, so it cannot be easily stopped and restarted. The whole &plasma; environment depends on it.

## "Unable to Fetch Item from Backend ... [LRCONFLICT]"

This problem is directly related to &akonadi; bug #283682, which has been a thorn in the side of &kmail; since October, 2011. There is a timing / co-ordination problem with asynchronous processing of message filters. Once in a while, a filter rule that moves messages to a different folder "hiccups", and produces more than one database entry for a message that has been moved. When you try to open the second copy of such a message, the error message "Unable to fetch item from backend ...[LRCONFLICT]" appears. Such phantom messages cannot be deleted or moved to trash using &kmail;'s built-in functions. But you can get rid of them. Here's how you do it.

1. First, exit the &kmail; program. This may not be necessary, but better safe than sorry.

2. You can learn how many corrupted messages are present by using `akonadictl`.

       ~ $ akonadictl fsck 2>&1 | grep ^Found
       Found 6 external files.
       Found 6 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 9 items without RID.
       Found 0 dirty items.

   In this instance, there are nine duplicated messages (without RID).

3. You need to know how to connect directly to the mysql server. Use the `ps` and `grep` commands to do this.

       ~ $ ps ux | grep mysql
       david     8788  0.2  0.9 3736292 153936 ?      Sl   06:45   0:16 /usr/sbin/mysqld
       --defaults-file=/home/david/.local/share/akonadi/mysql.conf
       --datadir=/home/david/.local/share/akonadi/db_data/
       --socket=/run/user/1000/akonadi/mysql.socket
       --pid-file=/run/user/1000/akonadi/mysql.pid
       david    24275  0.0  0.0   8056  2144 pts/1    S+   08:24   0:00 grep --colour=auto mysql

4. Invoke the mysql server program using the socket information from step 3 and issue three mysql commands, as illustrated below.

       ~ $ mysql --socket=/run/user/1000/akonadi/mysql.socket                 <==
       Welcome to the MariaDB monitor.  Commands end with ; or \g.
       Your MariaDB connection id is 114
       Server version: 10.5.10-MariaDB Source distribution

       Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

       Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

       MariaDB [(none)]> use akonadi;                                         <==
       Reading table information for completion of table and column names
       You can turn off this feature to get a quicker startup with -A

       Database changed
       MariaDB [akonadi]> delete from pimitemtable where remoteid is NULL;    <==
       Query OK, 9 rows affected (0.003 sec)

       MariaDB [akonadi]> \q                                                  <==
       Bye

   The three mysql commands are "use akonadi;", "delete from pimitemtable where remoteid is NULL;", and "\q". After you say "mysql --socket= ..." you will be in a dialog with the mysql server (aka "MariaDB"), which provides a > prompt. The entire dialog is presented here, for clarity. User input lines are marked with <== in the preceding illustration.

When you restart &kmail;, those pesky duplicate messages will be gone. They were merely phantoms caused by the NULL pointers in the mysql database tables.

## Keeping &kmail;'s Auxiliary Storage Areas Clean

&kmail; stores data in several different places on your machine. Most of these places are inside the `~/.local/share/` directory somewhere. For instance, on most Linux distros, your Local Folders are in `~/.local/share/local-mail/` . &akonadi; stores most of its data in `~/.local/share/akonadi/` .

    ~ $ cd .local/share/akonadi
    ~/.local/share/akonadi $ ls
    Akonadi.error      db_data  file_db_data     mysql.conf  socket-localhost-default
    Akonadi.error.old  db_misc  file_lost+found  search_db

`Akonadi.error` and `Akonadi.error.old` are log files that are created whenever &akonadi; stops and restarts. Text file `mysql.conf` is a configuration file for the mysqld daemon that serves as &akonadi;'s backend. The two directories `db_data` and `search_db` contain the actual mysql database tables. There are also a couple of mysql log files in `db_data` that might be helpful if and when &akonadi; acts up.

The two directories `file_db_data` and `file_lost+found` contain auxiliary data associated with asynchronous processing. &akonadi; does not automatically clean out the `file_lost+found` directory, so you may wish to clean those files up manually from time to time (⪚, with &dolphin;). &akonadi; does try to clean the `file_db_data` directory out after it has merged everything into the main database files, but sometimes junk piles up in there. Use this command

    find .local/share/akonadi/file_db_data/ -type f | xargs rm

to fix this when it happens. (If the directory `file_db_data` is already clean, the "find" command shown above will return an error.)

## 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 &Ctrl;L File Check Mail; &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!