KMail TroubleshootingTable of Contents
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.
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.
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.