/offlineimap/head: changeset 344

offlineimap/head/offlineimap.sgml

@@ -11,7 +11,7 @@
     <refentryinfo>
       <address><email>jgoerzen@complete.org</email></address>
       <author><firstname>John</firstname><surname>Goerzen</surname></author>
-      <date> $Date: 2003-01-08 09:08:01 -0600 (Wed, 08 Jan 2003) $ </date>
+      <date> $Date: 2003-01-08 09:13:21 -0600 (Wed, 08 Jan 2003) $ </date>
     </refentryinfo>
 
     <refmeta>
@@ -676,7 +676,64 @@ def test_mycmp():
       </refsect2>
     </refsect1>
       
+    <refsect1>
+      <title>Errors</title>
+      <para>
+	If you get one of some frequently-encountered or confusing errors,
+	please check this section.
+      </para>
+      
+      <refsect2>
+	<title>UID validity problem for folder</title>
+	<para>IMAP servers use a unique ID (UID) to refer to a specific message.
+	  This number is guaranteed to be unique to a particular message
+	  <emphasis>forever</emphasis>.
+	  No other message in the same folder will ever get the same
+	  UID.  UIDs are an integral part of &OfflineIMAP;'s synchronization
+	  scheme; they are used to match up messages on your computer to
+	  messages on the server.
+	</para>
 
+	<para>
+	  Sometimes, the UIDs on the server might get reset.  Usually this will
+	  happen if you delete and then recreate a folder.  When you create a
+	  folder, the server will often start the UID back from 1.  But
+	  &OfflineIMAP; might still have the UIDs from the previous folder by the
+	  same name stored.  &OfflineIMAP; will detect this condition and skip the
+	  folder.  This is GOOD, because it prevents data loss.
+	</para>
+
+	<para>
+	  You can fix it by removing your local folder and cache data.  For
+	  instance, if your folders are under <filename>~/Folders</filename>
+	  and the folder with the problem is INBOX, you'd type this:
+	</para>
+
+	<programlisting>rm -r ~/Folders/INBOX
+rm -r ~/.offlineimap/AccountName/INBOX</programlisting>
+
+	<para>
+	  (Of course, replace AccountName with the account name as specified
+	  in <filename>~/.offlineimaprc</filename>).
+	</para>
+
+	<para>Next time you run &OfflineIMAP;, it will re-download
+	  the folder with the
+	  new UIDs.  Note that the procedure specified above will lose any local
+	  changes made to the folder.
+	</para>
+
+	<para>
+	  Some IMAP servers are broken and do not support UIDs properly.  If you
+	  continue to get this error for all your folders even after performing
+	  the above procedure, it is likely that your IMAP server falls into
+	  this category.  &OfflineIMAP; is incompatible with such servers.
+	  Using &OfflineIMAP; with them will not destroy any mail, but at the same time,
+	  it will not actually synchronize it either.  (&OfflineIMAP; will detect
+	  this condition and abort prior to synchronization.)
+	</para>
+      </refsect2>
+    </refsect1>
 
     <refsect1>
       <title>See Also</title>