Troubleshooting

KMail doesn't send mail
Some users find that mail does not go out, and it appears that is missing, even though the Settings page looks correct. It has been reported that this is cured by opening akonadiconsole and adding Mail Dispatcher Agent.
If the computer was suddenly turned off in suspend mode (⪚ by a power cut) sometimes e-mails simply stay in the outbox without being sent, but no error message is generated either. This may be due to the fact that the Mail Dispatcher Agent is set to offline in the configuration file during suspend and is not changed back due to the crash. Edit the following file:
~/.config/akonadi/agent_config_akonadi_maildispatcher_agent
and change

[Agent]
Online=false

to

[Agent]
Online=true

Clean start after a failed migration
In case migration from 1 to 2 fails or you have weird problems after it, you can try to do a clean import of your data, instead of migrating the existing settings. Be warned, this needs more manual setup, so do only if you are confident of setting up your accounts again; it can generate a large amount of network traffic for resources.
Stop Akonadi and related applications
quit //, and issue this command:
akonadictl stop
Make sure no Akonadi or MySQL process is running:
ps ux | grep mysql
ps ux | grep akonadi
They should not show anything else but the grep process itself.
Remove old Akonadi database and config
Delete the following folders
~/.local/share/akonadi
~/.config/akonadi
Delete also the files starting with akonadi from ~/.kde4/share/config
Restart Akonadi server
akonadictl start
Add back the accounts
Now it is time to add your account back. You can use () for it, or you can use the akonadiconsole tool.
In : Settings Configure KMail Accounts and use Add.
If you use , add a new E-Mail server. If you want disconnected mode (so you can read the mails offline), enable it on the Advanced tab. Be sure to check that you are subscribed to all your important folders.
You might already see a Local folder resource. This points to a local maildir folder. You can either modify this to point to your existing maildir folders or you can add a new resource for local mails.
When adding a maildir resource you can choose between Mail Folder or Maildir. Unless you have a mixed folder containing both maildir folders and mbox files, you should choose Maildir. For independent mbox files, like the one in the /var/spool/mail, you can set up a new MBox folder.
Add the POP3 accounts as well. If you have multiple Local Folders set up, on the Advanced tab, choose the destination folder where the newly downloaded mails are put.
For all accounts, configure the mail check interval. For Local folders disable interval checking and also disable Include in manual mail check in the Retrieval options.
Add the sending (SMTP) accounts.
Fix your filters, identities and favorite folders
If you have client side filtering (common with POP3 mails), go to Settings Configure Filters and fix the destination folder for the filters, they most probably are wrong. Otherwise mails will end up in folders you don't expect.
Spam filter (at least in version 4.7.3 and earlier) does not work as expected in that the rule that the wizard creates does not send spam to the folder you have defined.
The workaround for this is to change the spam and spam unsure (if the spam filter you use supports that) from looking at Status-fields in the header X-Spam-Status to look Anywhere in headers for X-your spam filter-Classification: SPAM or unsure. Look at the filters the wizard creates and copy the contains part. Example for Spambayes: X-Spambayes-Classification: spam and X-Spambayes-Classification: unsure.
You also need to verify the identity settings and set the sent-mail, drafts and templates folders to point to the right folders. To do that go to Settings Configure KMail Identities, modify the identity, go to the Advanced tab and modify the above mentioned folder settings.
Check also that your Favorite Folders are the ones you have chosen before.
Initiate a mail check
Start a mail check for your accounts. It is suggested doing it per account.
First check for , if you have it.
Next check (import) your local mails. One solution is to do a full check in one go File Check Mail In and select the local account; the other is to click one by one on the folders, that should initiate the check for that folder (alternatively right click on the folder name and select Update Folder).
The initial import might be slow and could use a lot of memory, especially if you have folders with a large amount of mail. In that case per-folder check is preferred. If the check (complete or for one folder) is finished and the memory usage is still high, you could restart the Akonadi server — as seen above — or just the maildir agent, if you use akonadiconsole. Do not worry, this high memory usage is only for initial import.
Initiate a check mail for POP3 resources.
Hopefully after these steps, you will have a much nicer experience.

Local Folders is added over and over
In some cases you might end up with a maildir account pointing to a certain place (like $HOME/Mail), but you still see a Local Folders folder in the folder list with Inbox/Outbox/Trash/Drafts/ subfolders and keeps putting mails there, especially sent mails.
The problem is that certain folders are marked as special folders (system folders) and if you don't have them, cannot operate correctly. That is the reason why it keeps re-creating that folder.
At this time there is no easy way to change this in the UI for all types of special folders. Here is what you can do:
The Sent-Mail, Drafts and Templates folder is configurable for each identity. Go to Settings Configure KMail Identities, select your identity, click on Modify, go to the Advanced tab and set the folders to point to the right place.
The default Inbox is configurable for each POP3 account. Go to Settings Configure KMail Account, select your POP3 account, click on Modify go to the Advanced tab and set the Destination folder.
For IMAP accounts you can configure the Trash folder. Do as above. The setting name is Trash folder.
The most problematic part is the Outbox. First, locate specialmailcollectionsrc in your configuration directory ($HOME/.kde4/share/config or similar). It contains something like this:
[SpecialCollections] DefaultResourceId=akonadi_maildir_resource_0
Now start akonadiconsole, on the Agents tab locate your local account for your Outbox folder, click on it and note the identifier that appears in the lower part (akonadi_maildir_resource_XXX or similar). Put this identifier in the above shown specialmailcollectionsrc, by replacing the existing one.
After that restart akonadi (you can do from the akonadiconsole, Server Restart Server or from command line with:
akonadictl restart
Now remove the Local Folders that you don't want to use anymore.
If it keeps reappearing and the Mail Dispatcher Agent still crashes, you need to do one more thing in akonadiconsole. Go to the Browser tab, find the outbox you want to use, right click on it, select Folder Properties, Attributes tab, enter SpecialCollectionAttribute then click Add, double click on the Value near the SpecialCollectionAttribute and enter outbox. Add also another attribute, the attribute name has to be ENTITYDISPLAY and the value ("outbox" "mail-folder-outbox" "" ()) (just copy paste from here). Restart akonadi and now you should be able to remove completely the unneeded local folder account.

You get the error Unable to fetch item from backend when entering IMAP folder
There are a number of possible reasons for this and it is something the team hopes to tackle in time. Meanwhile, there 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 mostly a matter of restarting so can fetch those pesky items... Some possible steps:
Use F2 or to type: kquitapp kmail, then wait a minute, then akonadictl stop, wait a minute, type akonadictl start, wait a minute, type kmail. This stops (closing all windows), stops the backend, starts the backend, starts . Having a working internet connection increases the chances of success. Sometimes, you can also just do kquitapp kmail, wait a minute, and start again. Often, a few restarts seem to be needed. It is unclear what is the reason for this, but on bad network connections it is more likely to happen.
See also the below item for how akonadiconsole can be helpful.

Your mails are not being sent, without error messages
If does not send mail without saying anything, the agent responsible for dispatching the messages can be stuck. Of course, you need to ensure you have proper network connectivity for mail to be sent!
To remedy this, it might help to abort the current action and restart it. First, quit by using (F2) or and typing: kquitapp kmail. Note that a normal F4 or File Quit does not do the trick! Wait a minute, then start again. Now start akonadiconsole using (F2) or . Go to the Mail Dispatcher Agent, do a right-click and abort the current action. You will most likely get some error messages popping up. Go back to 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 or restarting things as mentioned in workaround 2 of the problem above this one.
akonadiconsole can be quite helpful for a number of situations as it shows all the agents, the separate components of the backend. You can stop and start them, put them in offline mode, abort ongoing actions It can be very helpful when things get stuck.