Commit 8d2ac17a authored by David Bryant's avatar David Bryant 💬
Browse files

Updating chapter 7 of KMail documentation -- "troubleshooting"

parent 238c0621
Pipeline #75598 canceled with stage
......@@ -3,40 +3,208 @@
<chapterinfo>
<authorgroup>
<author>
<personname>
<firstname>This chapter was converted from the KDE UserBase <ulink url="https://userbase.kde.org/Special:MyLanguage/KMail/FAQs_Hints_and_Tips">KMail/FAQs Hints and Tips</ulink> page.</firstname>
<surname></surname>
</personname>
</author>
<personname>
<firstname>Portions of this chapter were converted from the KDE UserBase <ulink
url="https://userbase.kde.org/Special:MyLanguage/KMail/FAQs_Hints_and_Tips">KMail/FAQs Hints and Tips</ulink> page in 2012.</firstname>
</personname>
</author>
<author>
&David.Bryant;
&David.Bryant.mail;
</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>
<date>2012-07-28</date>
<releaseinfo>&kde; SC 4.9</releaseinfo>
</authorgroup>
<date>2021-08-08</date>
<releaseinfo>5.14.2 (Applications 20.04.2)</releaseinfo>
</chapterinfo>
<title>&kmail; Troubleshooting</title>
<sect1 id="kmail2-doesnt-send-mail"><title>KMail doesn't send mail</title>
<para>Some users find that mail does not go out, and it appears that &SMTP; is missing, even though the <guilabel>Settings</guilabel> page looks correct. It has been reported that this is cured by opening <application>akonadiconsole</application> and adding Mail Dispatcher Agent.
</para>
<para>If the computer was suddenly turned off in suspend mode (&eg; 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 <quote>offline</quote> in the configuration file during suspend and is not changed back due to the crash. Edit the following file:
</para>
<para><filename>~/.config/akonadi/agent_config_akonadi_maildispatcher_agent</filename>
</para>
<para>and change
</para>
<para><screen>
[Agent]
Online=false</screen>
</para>
<para>to
</para>
<para><screen>
[Agent]
Online=true</screen>
</para>
<sect1 id="introduction-to-akonadi">
<title>Introduction to &akonadi;</title>
<para>&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 <ulink
url="https://userbase.kde.org/Special:MyLanguage/KMail/FAQs_Hints_and_Tips">KMail/FAQs Hints and Tips</ulink>
in the &kde; UserBase Wiki. Or visit <ulink url="https://bugs.kde.org">&kde;'s main bug tracking page</ulink>
to learn about bugs of a more recent vintage.</para>
<para>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;).</para>
<para> There are two application programs that permit one to interact with the &akonadi; server directly: <code>akonadictl</code>
(a terminal-oriented control program), and <code>akonadiconsole</code> (a GUI application). Here is a little information about
those two programs.</para>
<para>&nbsp;</para><!-- add whitespace -->
<sect2 id="intro-to-akonadictl">
<title>The Akonadictl Control Program</title>
<screenshot>
<screeninfo>&akonadi; status report</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="akonadictl.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>&akonadi; status report</phrase>
</textobject>
<caption>
<para>Akonadictl Status Report, 32 Agents Running</para>
</caption>
</mediaobject>
</screenshot>
<para>&nbsp;</para><!-- add whitespace -->
<para>The preceding screenshot illustrates one of the commands one may use with the <code>akonadictl</code> program. Here
are all the commands <code>akonadictl</code> recognizes.</para>
<para><screen>~$ akonadictl start</screen> Starts the &akonadi; server.</para>
<para><screen>~$ akonadictl stop</screen> Stops the &akonadi; server.</para>
<para><screen>~$ akonadictl restart</screen> Stops the &akonadi; server, then launches it anew.</para>
<para><screen>~$ akonadictl status</screen> Produces the status report illustrated in the preceding screenshot.</para>
<para><screen>~$ akonadictl instances</screen> Lists the &akonadi; server instances (more than one can
be running at the same time).</para>
<para><screen>~$ akonadictl vacuum</screen> Cleans up &akonadi;'s storage, or at least tries to do that.</para>
<para><screen>~$ akonadictl fsck</screen> 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.</para>
<para>
<screen>~ $ akonadictl fsck 2>&amp;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.</screen> <!-- Can't indent here ... messes up the output. -->
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 <emphasis>must</emphasis> be corrected. See <link
linkend="resource-conflict-error">"Unable to Fetch Item ..."</link> and also <link
linkend="dealing-with-dirt">Correcting &kmail;'s "Dirty" Items</link>, below.
</para>
<para>&nbsp;</para><!-- add whitespace -->
</sect2>
<sect2 id="intro-to-akonadiconsole">
<title>The Akonadiconsole Program</title>
<screenshot>
<screeninfo>What akonadiconsole looks like</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="akonadiconsole.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>What akonadiconsole looks like</phrase>
</textobject>
<caption>
<para>Akonadiconsole in action</para>
</caption>
</mediaobject>
</screenshot>
<para>&nbsp;</para><!-- add whitespace -->
<para>The <code>akonadiconsole</code> program provides twelve different "windows" into the inner
workings of the &PIM; applications. Here is a brief summary of the available views.</para>
<variablelist>
<varlistentry id="ak-console-agents">
<term><guilabel>Agents</guilabel> tab.</term>
<listitem><para>Here you can see a list of the user agents (processors).</para></listitem>
</varlistentry>
<varlistentry id="ak-console-browser">
<term><guilabel>Browse</guilabel> tab.</term>
<listitem><para>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.</para></listitem>
</varlistentry>
<varlistentry id="ak-console-debugger">
<term><guilabel>Debugger</guilabel> tab.</term>
<listitem><para>Here you can turn debugging on and off, and view the debug message log.</para></listitem>
</varlistentry>
<varlistentry id="ak-console-logging">
<term><guilabel>Logging</guilabel> tab.</term>
<listitem><para>This tab lets you view messages emitted by various &akonadi; components..</para></listitem>
</varlistentry>
<varlistentry id="ak-console-db-browser">
<term><guilabel>DB Browser</guilabel> tab.</term>
<listitem><para>Use this tab to peek inside the mysql database. There are many different tables.</para></listitem>
</varlistentry>
<varlistentry id="ak-console-db-console">
<term><guilabel>DB Console</guilabel> tab.</term>
<listitem><para>Here you can query the mysql database.</para></listitem>
</varlistentry>
<varlistentry id="ak-console-query">
<term><guilabel>Query Debugger</guilabel> tab.</term>
<listitem><para>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.</para></listitem>
</varlistentry>
<varlistentry id="ak-console-tracker">
<term><guilabel>Job Tracker</guilabel> tab.</term>
<listitem><para>The &PIM; applications perform various functions by initiating "jobs". Use
this tab to toggle job tracking on and off.</para></listitem>
</varlistentry>
<varlistentry id="ak-console-scheduler">
<term><guilabel>Resources Schedulers</guilabel> tab.</term>
<listitem><para>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
<filename>~/.config/akonadi/</filename> directory.</para></listitem>
</varlistentry>
<varlistentry id="ak-console-notif-monitor">
<term><guilabel>Notification Monitor</guilabel> tab.</term>
<listitem><para>Use this tab to monitor notifications sent by various &akonadi; resources.</para></listitem>
</varlistentry>
<varlistentry id="ak-console-search">
<term><guilabel>Item Search</guilabel> tab.</term>
<listitem><para>This tab provides a generic search function. Searches can be restricted to Calendar, Contact,
Email, or Note.</para></listitem>
</varlistentry>
<varlistentry id="ak-console-monitors">
<term><guilabel>Monitors</guilabel> tab.</term>
<listitem><para>Here you can see a list of all the monitors running under &akonadi;, and also view
their properties. Agents, resources, and even some appliction programs are monitored.</para></listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>
<sect1 id="clean-start-after-a-failed-migration"><title>Clean start after a failed migration</title>
<!-- <sect1 id="kmail2-doesnt-send-mail">
<title>KMail doesn't send mail</title>
<para>Some users find that mail does not go out, and it appears that &SMTP; is missing, even though the
<guilabel>Settings</guilabel> page looks correct. It has been reported that this is cured by opening
<application>akonadiconsole</application> and adding Mail Dispatcher Agent.</para>ttps://bugs.kde.org/show_bug.cgi?id=283682
<para>If the computer was suddenly turned off in suspend mode (&eg; 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 <quote>offline</quote> in the configuration file during suspend and
is not changed back due to the crash. Edit the following file:</para>
<para><filename>~/.config/akonadi/agent_config_akonadi_maildispatcher_agent</filename> and change</para>
<para><screen>[Agent] Online=false</screen></para>
<para>to</para>
<para><screen>[Agent] Online=true</screen></para>
</sect1> --> <!-- This section removed 8/8/2021. -->
<!-- <sect1 id="clean-start-after-a-failed-migration"><title>Clean start after a failed migration</title>
<para>In case migration from &kmail; 1 to &kmail; 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 &kmail; accounts again; it can generate a large amount of network traffic for &IMAP; resources.
</para>
<orderedlist>
......@@ -72,7 +240,7 @@ Online=true</screen>
<para>Delete also the files starting with <emphasis>akonadi</emphasis> from <filename role="directory">~/.kde4/share/config</filename>
</para>
</listitem>
<listitem>
<listitem>ttps://bugs.kde.org/show_bug.cgi?id=283682
<para>Restart Akonadi server
</para>
<para><userinput><command>akonadictl start</command></userinput>
......@@ -129,9 +297,9 @@ Online=true</screen>
</orderedlist>
<para>Hopefully after these steps, you will have a much nicer &kmail; experience.
</para>
</sect1>
</sect1> --> <!-- This section removed 8/8/2021. -->
<sect1 id="local-folders-is-added-over-and-over"><title>Local Folders is added over and over</title>
<!-- <sect1 id="local-folders-is-added-over-and-over"><title>Local Folders is added over and over</title>
<para>In some cases you might end up with a maildir account pointing to a certain place (like <filename>$HOME/Mail</filename>), but you still see a <guilabel>Local Folders</guilabel> folder in the folder list with Inbox/Outbox/Trash/Drafts/&etc; subfolders and &kmail; keeps putting mails there, especially sent mails.
</para>
<para>The problem is that certain folders are marked as special folders (system folders) and if you don't have them, &kmail; cannot operate correctly. That is the reason why it keeps re-creating that folder.
......@@ -158,44 +326,239 @@ DefaultResourceId=akonadi_maildir_resource_0</userinput>
</para>
<para>If it keeps reappearing and the <guilabel>Mail Dispatcher Agent</guilabel> still crashes, you need to do one more thing in <application>akonadiconsole</application>. Go to the <guilabel>Browser</guilabel> tab, find the outbox you <emphasis>want</emphasis> to use, right click on it, select <guilabel>Folder Properties</guilabel>, <guilabel>Attributes</guilabel> tab, enter <userinput>SpecialCollectionAttribute</userinput> then click <guilabel>Add</guilabel>, double click on the <guilabel>Value</guilabel> near the <guilabel>SpecialCollectionAttribute</guilabel> and enter <userinput>outbox</userinput>. Add also another attribute, the attribute name has to be <guilabel>ENTITYDISPLAY</guilabel> and the value <userinput>("outbox" "mail-folder-outbox" "" ())</userinput> (just copy paste from here). Restart <application>akonadi</application> and now you should be able to remove completely the unneeded local folder account.
</para>
</sect1> --> <!-- This section removed 8/8/2021. -->
<sect1 id="unable-to-fetch-item-from-backend">
<title>"Unable to Fetch Item from Backend" When Entering &IMAP; Folder</title>
<para>There are at least two possible reasons for this. Here are some workarounds.</para>
<variablelist>
<varlistentry>
<term>Workaround 1</term>
<listitem>
<itemizedlist>
<listitem><para>edit <filename>~/.local/share/akonadi/mysql.conf</filename></para></listitem>
<listitem><para>Under the <guilabel>[mysql]</guilabel> section, add: <userinput>binlog_format=row</userinput></para></listitem>
</itemizedlist>
<para>If this does not work, try workaround 2 (below).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Workaround 2</term>
<listitem>
<para>This one is a matter of restarting so &kmail; can fetch those pesky items. Some possible steps include:</para>
<para>Use <keycombo>&Alt;<keycap>F2</keycap></keycombo> (&krunner;) or &konsole; to type <userinput><command>kquitapp
kmail</command></userinput> , then wait a minute, then <userinput><command>akonadictl stop</command></userinput> . Wait
a minute, type <userinput><command>akonadictl start</command></userinput> , wait a minute, then type <userinput>
<command>kmail</command></userinput> . This stops &kmail; (closing <emphasis>all</emphasis> 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 <userinput><command>kquitapp kmail</command></userinput> , 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.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>See also <link linkend="your-mails-are-not-being-sent">the next topic</link> to learn how
<application>akonadiconsole</application> can be helpful.</para>
</sect1>
<sect1 id="you-get-the-error-unable-to-fetch-item-from-backend-when-entering-imap-folder"><title>You get the error Unable to fetch item from backend when entering IMAP folder</title>
<para>There are a number of possible reasons for this and it is something the &kmail; team hopes to tackle in time. Meanwhile, there are some workarounds:
</para>
<variablelist>
<varlistentry>
<term>Workaround 1</term>
<listitem>
<itemizedlist>
<listitem><para>edit <filename>~/.local/share/akonadi/mysql.conf</filename></para></listitem>
<listitem><para>Under the <guilabel>[mysql]</guilabel> section, add: <userinput>binlog_format=row</userinput></para></listitem>
</itemizedlist>
<para>If this does not work, try workaround 2 (below).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Workaround 2</term>
<listitem>
<para>This one is mostly a matter of restarting so &kmail; can fetch those pesky items... Some possible steps:</para>
<para>Use <keycombo>&Alt;<keycap>F2</keycap></keycombo> or &konsole; to type: <userinput><command>kquitapp kmail</command></userinput>, then wait a minute, then <userinput><command>akonadictl stop</command></userinput>, wait a minute, type <userinput><command>akonadictl start</command></userinput>, wait a minute, type <userinput><command>kmail</command></userinput>. This stops &kmail; (closing <emphasis>all</emphasis> windows), stops the &kmail; backend, starts the &kmail; backend, starts &kmail;. Having a working internet connection increases the chances of success. Sometimes, you can also just do <userinput><command>kquitapp kmail</command></userinput>, wait a minute, and start &kmail; 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.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>See also the below item for how <application>akonadiconsole</application> can be helpful.
</para>
<sect1 id="your-mails-are-not-being-sent">
<title>Your Emails Are Not Being Sent, Without Error Messages</title>
<para>If &kmail; does not send mail without saying anything, the <quote>agent</quote> responsible for dispatching
messages may be stuck. Of course, you should first verify you have proper network connectivity so mail can be sent!</para>
<para>To remedy this, it might help to abort the current action and restart it. First, quit &kmail; by using &krunner;
(<keycombo>&Alt;<keycap>F2</keycap></keycombo>) or &konsole; and typing: <userinput><command>kquitapp kmail</command></userinput> .
Note that a normal <keycombo>&Alt;<keycap>F4</keycap></keycombo> or <menuchoice><guimenu>File</guimenu><guimenuitem>Quit</guimenuitem>
</menuchoice> does <emphasis>not</emphasis> do the trick! Wait a minute, then start &kmail; again. Now start
<application>akonadiconsole</application> using &krunner; (<keycombo>&Alt;<keycap>F2</keycap></keycombo>) or &konsole;. Go to the
<guilabel>Mail Dispatcher Agent</guilabel> (under the <guilabel>Agents</guilabel> 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 <menuchoice><guimenu>File</guimenu>
<guimenuitem>Send Queued Messages</guimenuitem></menuchoice>. Now it might work. If not, instead of aborting the current action,
try toggling the offline/online status of the <guilabel>Mail Dispatcher Agent</guilabel> (same context menu) or restarting things
as mentioned in workaround 2 of <link linkend="unable-to-fetch-item-from-backend"> the previous topic</link>.</para>
<para><note><para>akonadiconsole can be quite helpful for a number of situations because it shows all the <quote>agents</quote>,
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.</para></note></para>
<para>Sometimes the <guilabel>Mail Dispatcher Agent</guilabel> 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.</para>
</sect1>
<sect1 id="your-mails-are-not-being-sent-without-error-messages"><title>Your mails are not being sent, without error messages</title>
<para>If &kmail; does not send mail without saying anything, the <quote>agent</quote> responsible for dispatching the messages can be stuck. Of course, you need to ensure you have proper network connectivity for mail to be sent!
</para>
<para>To remedy this, it might help to abort the current action and restart it. First, quit &kmail; by using &krunner; (<keycombo>&Alt;<keycap>F2</keycap></keycombo>) or &konsole; and typing: <userinput><command>kquitapp kmail</command></userinput>. Note that a normal <keycombo>&Alt;<keycap>F4</keycap></keycombo> or <menuchoice><guimenu>File</guimenu><guimenuitem>Quit</guimenuitem></menuchoice> does <emphasis>not</emphasis> do the trick! Wait a minute, then start &kmail; again. Now start <application>akonadiconsole</application> using &krunner; (<keycombo>&Alt;<keycap>F2</keycap></keycombo>) or &konsole;. Go to the <guilabel>Mail Dispatcher Agent</guilabel>, do a right-click and abort the current action. You will most likely get some error messages popping up.
Go back to &kmail; and choose <menuchoice><guimenu>File</guimenu><guimenuitem>Send Queued Messages</guimenuitem></menuchoice>. Now it might work. If not, instead of aborting the current action, try toggling the offline/online status of the <guilabel>Mail Dispatcher Agent</guilabel> or restarting things as mentioned in workaround 2 of the problem above this one.
</para>
<para><note><para>akonadiconsole can be quite helpful for a number of situations as it shows all the <quote>agents</quote>, 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 things get stuck.</para></note>
</para>
<sect1 id="resource-conflict-error">
<title>"Unable to Fetch Item from Backend ... [LRCONFLICT]"</title>
<para>This problem is directly related to <ulink url="https://bugs.kde.org/show_bug.cgi?id=283682">&akonadi; bug #283682</ulink>,
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 <emphasis>can</emphasis> get rid of them. Here's how you do it.</para>
<procedure>
<step><para>First, exit the &kmail; program. This may not be necessary, but better safe than sorry.</para></step>
<step><para>You can learn how many corrupted messages are present by using <code>akonadictl</code>.
<screen>~ $ akonadictl fsck 2>&amp;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.</screen> <!-- Can't indent here ... messes up the output. -->
In this instance, there are nine duplicated messages (without RID).</para>
<para>&nbsp;</para><!-- add whitespace --></step>
<step><para>You need to know how to connect directly to the mysql server. Use the <code>ps</code> and
<code>grep</code> commands to do this.
<screen>~ $ 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</screen></para>
<para>&nbsp;</para><!-- add whitespace --></step>
<step><para>Invoke the mysql server program using the socket information from step 3 and issue three mysql
commands, as illustrated below.
<screen>~ $ mysql --socket=/run/user/1000/akonadi/mysql.socket &lt;==
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; &lt;==
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; &lt;==
Query OK, 9 rows affected (0.003 sec)
MariaDB [akonadi]> \q &lt;==
Bye</screen>
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 &gt; prompt.
The entire dialog is presented here, for clarity. User input lines are marked with &lt;== in the preceding
illustration.</para></step>
</procedure>
<para>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.</para>
</sect1>
<sect1 id="cleaning-aux-storage">
<title>Keeping &kmail;'s Auxiliary Storage Areas Clean</title>
<para>&kmail; stores data in several different places on your machine. Most of these places are inside the
<filename>~/.local/share/</filename> directory somewhere. For instance, on most Linux distros, your
<guilabel>Local Folders</guilabel> are in <filename>~/.local/share/local-mail/</filename> . &akonadi; stores
most of its data in <filename>~/.local/share/akonadi/</filename> .
<screen>~ $ 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
</screen></para>
<para><filename>Akonadi.error</filename> and <filename>Akonadi.error.old</filename> are log files that are created
whenever &akonadi; stops and restarts. Text file <filename>mysql.conf</filename> is a configuration file for
the mysqld daemon that serves as &akonadi;'s backend. The two directories <filename>db_data</filename> and
<filename>search_db</filename> contain the actual mysql database tables. There are also a couple of mysql
log files in <filename>db_data</filename> that mignt be helpful if and when &akonadi; acts up.</para>
<para>The two directories <filename>file_db_data</filename> and <filename>file_lost+found</filename> contain auxiliary
data associated with asynchronous processing. &akonadi; does not automatically clean out the
<filename>file_lost+found</filename> directory, so you may wish to clean those files up manually from time to time
(&eg;, with &dolphin;). &akonadi; does try to clean the <filename>file_db_data</filename> directory out after it has merged
everything into the main database files, but sometimes junk piles up in there. Use this command
<screen>find .local/share/akonadi/file_db_data/ -type f | xargs rm</screen> to fix this when it happens. (If the directory
<filename>file_db_data</filename> is already clean, the "find" command shown above will return an error.)</para>
</sect1>
<sect1 id="dealing-with-dirt">
<title>Correcting &kmail;'s "Dirty" Items</title>
<para>This problem is directly related to <ulink url="https://bugs.kde.org/show_bug.cgi?id=436550">&akonadi; bug #436550</ulink>,
which was reported in April, 2021. It results from the "dirty" items occasionally found by <code>akonadictl fsck</code>.
<screen>~ $ akonadictl fsck 2>&amp;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.</screen> <!-- Can't indent here ... messes up the output. -->
</para>
<para>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.</para>
<para>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.</para>
<para>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.</para>
<procedure>
<step><para>Exit &kmail; and stop the &akonadi; server with a terminal command: <code>akonadictl stop</code> .</para></step>
<step><para>Make a backup copy of all your email messages. You may be able to use <ulink url="help:/pimdataexporter">PIM
Data Exporter</ulink> for this purpose. Or you may use &ark; to make an archive, or &dolphin; to make a second copy of
<filename>~/.local/share/local-mail/</filename> somewhere else on your hard disk. If you're adventurous, you might just
rename your local folders directory to something like <filename>local-mail-save</filename> . But it's safer to be sure
you have a backup copy of your messages before you proceed.</para></step>
<step><para>You should also make a backup copy of any filters you have created, and make sure you know how to restore any
custom <guilabel>Sent mail folder</guilabel>, <guilabel>Drafts folder</guilabel>, or <guilabel>Templates folder</guilabel>
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.</para></step>
<step><para>Now delete all the folders inside of the directory <filename>local-mail</filename>, or rename that directory
to something like <filename>local-mail-save</filename> . 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).</para></step>
<step><para>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 <filename>~/.local/share/local-mail/</filename> directory.</para></step>
<step><para>Start &kmail; up again, and force &akonadi; to re-sync the database. The easiest way to do this is to <menuchoice>
<shortcut><keycombo action="simul">&Ctrl;<keycap>L</keycap></keycombo></shortcut><guimenu>File</guimenu><guimenuitem>Check
Mail</guimenuitem></menuchoice>; &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.</para></step>
<step><para>Finally, you will want to restore your mail filter rules backed up in step 3, and check that all the custom folder
items (<guilabel>Sent mail folder</guilabel>, &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!</para></step>
</procedure>
</sect1>
</chapter>
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment