Setting up Kontact to work as expected can be a difficult, so the following actions can be taken to troubleshoot some of the issues.
General Purpose Troubleshooting
Ensure you have the right packages installed
It is essential that you have all the right packets installed, so that’s always a good first check.
The following packages must come from the Kolab Systems repository:
Collecting relevant context information
To be able to diagnose any problem it is essential to try to collect as much relevant information as possible to guide the troubleshooting process. Here are some potentially useful questions to answer in a first bug report:
- What are the symptoms of the problem?
- Is the problem reproducible? If so:
- How exactly, step by step?
- Is the problem only reproducible from a specific state? If so, how can that state be reproduced?
- How often does this problem reoccur?
- Are multiple systems affected, or does it only occur on a single system?
- Is there anything special about the affected system(s)? (OS, network, remote, …)
- Are there known workarounds to “fix” the problem (even if temporary), or some other way to get back to a good state of the system?
Collecting debug output
During troubleshooting it is useful to monitor the debug-output of akonadi. All output is written to stdout/stderr, and it is therefore necessary to restart akonadi in a terminal window. To enable all relevant debugoutput open
kdebugdialog and either enable all debug output, or search for “akonadi” and enable all matches.
To enable extra debug output from the IMAP and Kolab resources set the IMAP_TRACE environment variable:
Finally it is necessary to restart akonadi using
akonadictl restart to get the debugoutput in the terminal window. For a more permanent setup it is possible to start akonadi using
akonadictl start &> /tmp/akonadi.output to collect all output of akonadi. Please note that the logfile can become very large if logging is enabled.
Close Kontact and stop korgac using:
To restart akonadi from the commandline use:
Alternatively use the “Restart Database” option in Kontacts “File” menu.
Run Akonadi Console
The Akonadi Console is a valuable debugging tool if things don’t work as expected. The command name is
Akonadi Console can be used to:
- Add/Remove resources
- Inspect the status of resource
- Trigger synchronization of resources
- Check the availability of folders and content
If data does not appear in the main applications, such as kmail or korganizer, it’s usually a good first step to check with akonadiconsole whether the underlying data is actually available in the system. You should typically check:
- The availability of the “Kolab” resource in the Agent/Resource tab and it’s status.
- The availability of the collection (Folder) in the Browser tab.
- The availability of the collection contents in the Browser tab after selecting the collection. In the case of the Kolab resource the “Remote Id” corresponds to the IMAP UID on the server.
Run akonadictl fsck
In some cases “akonadictl fsck” can detect and fix some database issues.
If there are no problems with the database “akonadictl fsck” does nothing.
To run it, first restart akonadi in a console:
This is necessary to see the generated output.
The self-check and repair process can then be triggered by issuing:
Please note that any work done will be reported in the console where you have restarted akonadi, and the whole process might take a while.
Ensure you are not mixing gpg2 and gpg. Kontact only works with gpg2. See also the “GPG key is not selectable and/or does not seem to work as expected” section below.
To get gpgme to generate a logfile export an environment variable like the following.
9 is the loglevel in this case (with 9 being the highest), and the path points to where the logfile will be generated.
Restart Kontact and then reproduce the problem. The generated logfile should hopefully give an indication on what exactly is going wrong.
To enable debug output for gpg-agent as well do the following:
Create ~/.gnupg/gpg-agent.conf if it is not existing and add:
Then restart gpg-agent using
gpgconf --kill gpg-agent
The debug output will then be created in the given logfile. Don’t forget to revert the configuration changes and restart gpg-agent again once you have collected the information required.
Baloo is the fulltext indexing component of Kontact.
Searching the xapian index directly
To search the baloo index directly use the following command:
baloosearch4 -e "Some string"
This should return some result if the string is contained within one of your emails, otherwise the email is not indexed.
A result looks like:
akonadi:52915 The emails subjectline
52915 is the akonadi item id in this case, which can be found using akonadiconsole.
Checking the folder configuration
Confirm that in KMail -> Folder Properties -> Maintentance tab that the fulltextindexing is enabled.
Trigger a full reindexing
This will reindex all data, and can thus take a long time.
qdbus org.freedesktop.Akonadi.Agent.akonadi_baloo_indexer / reindexAll
If all things fail, here’s how to start over. Unfortunately Kontacts configuration is tied in with its storage,
so to be on the safe side it’s necessary to remove all relevant configuration with your database.
This unfortunately means that any configuration that has been done on Kontact will be lost. If this is not done, it’s unpredictable what the consequences are, so this is not recommended.
Start by stoping kontact and akonadi:
killall kontact; killall korgac
Then remove all data:
rm -R ~/.kde/share/apps/akonadi_migration_agent
rm -R ~/.kde/share/config/akonadi*
rm -R ~/.local/share/akonadi
rm -R ~/.config/akonadi
rm -R ~/.local/share/baloo/email
rm -R ~/.local/share/baloo/calendars
rm -R ~/.local/share/baloo/notes
rm -R ~/.local/share/baloo/emailContacts
rm -R ~/.local/share/baloo/contacts
rm -R ~/.local/share/baloo/collections
Finally, remove all relevant kontact configuration files:
You can now start Kontact again.
Symptoms and relevant troubleshooting
Kontact no longer automatically receives new email messages
Normally Kontact should update automatically in a specified interval, if configured so.
The relevant setting can be found under:
“Settings” -> “Configure KMail” -> “Accounts”: Select the Kolab resource and click on modify.
Enable the “Enable interval mail checking” checkbox, and select a suitable interval (5min by default).
How to diagnose this Problem
To ensure this problem applies, first check the configuration. If the configuration is correct and the interval check is enabled (set it to 5min for testing), send an email to the account in question. You can ensure that it has arrived using the webinterface. Kontact should refresh automatically after the configured period and the email should appear. Please see “Collecting debug output” to collect relevant debugging information.
- Check the resource status in
akonadiconsole; in the “Agents” tab the status of the resource should be “Ready” if the resource is not currently synchronizing.
- Check if you can manually refresh the folder using
akonadiconsole; go to the “Browser” tab, right-click on the “Inbox” folder and select “Synchronize Folder”.
- Check if you can manually synchronize the collection tree using akonadiconsole; in the “Agents” tab, right-click on the resource and select “Synchronize” -> “Synchronize Collection Tree”. This should always result in some debug output activity containing the string “KolabRetrieveCollectionsTask”.
- Check if restarting akonadi resolves the problem;
Collecting debug information for a bug report
If it’s possible to resolve the problem temporarily by restarting akonadi, then it’s time to gather debug output to find the problem causing it. Ensure you’re collecting all relevant debug output as described under “Collecting debug output” above (including the “IMAP_TRACE” environment variable).
Wait for the problem to appear and as soon as you notice the problem, collect the debug-output to determine where the resource got stuck. We’re interested in all activities of the “akonadi_kolab_resource”.
GPG key is not selectable and/or does not seem to work as expected
If a GPG key is not selectable as signing key, or there are other problems where a key does not work as expected.
How to diagnose this Problem
This problem applies if you have gpg2 >= 2.1. Consult
List your keys on the commandline:
gpg2 --list-secret-keys John
If your key is not available within this list, Kontact will also not be able to use it.
If your key is available with the following command:
gpg --list-secret-keys John
Then you have used the old gpg tool instead of gpg2, resulting in the key being stored in an incompatible location. Kontact will thus not find it.
- Generate a new key as described here.
- Migrate the existing key using
gpg --export-secret-key USERID | gpg2 --import