Kontact Troubleshooting

Posted on by

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:

  • libkolabxml
  • libkolab
  • baloo
  • kdepimlibs
  • kdepim-runtime
  • kdepim
  • zanshin

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: export KDE_DEBUG=1

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.

Restart Kontact

Close Kontact and stop korgac using:

killall korgac

Restart Akonadi

To restart akonadi from the commandline use:

akonadictl restart

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 akonadiconsole.

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:
akonadictl restart

This is necessary to see the generated output.

The self-check and repair process can then be triggered by issuing:
akonadictl fsck

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.

Troubleshooting Encryption

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.

export GPGME_DEBUG=9:/home/user/mygpgme.log

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:

debug-level guru
log-file /home/user/gpgagent.log

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.

Troubleshooting Fulltextindexing

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

Starting over

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
akonadictl stop

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:
rm ~/.kde/share/config/kmail2rc
rm ~/.kde/share/config/kmailrc
rm ~/.kde/share/config/korgacrc

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.

Relevant Configuration

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.

Troubleshooting

  • 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; akonadictl restart

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 gpg2 --version.

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.

Troubleshooting

  • Generate a new key as described here.
  • Migrate the existing key using
    gpg --export-secret-key  USERID | gpg2 --import
Posted in Documentation and tagged , .