"Fossies" - the Fresh Open Source Software Archive
Member "getmail-5.16/docs/troubleshooting.txt" (31 Oct 2021, 12369 Bytes) of package /linux/misc/getmail-5.16.tar.gz:
As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard
) with prefixed line numbers.
Alternatively you can here view
the uninterpreted source code file.
See also the latest Fossies "Diffs"
side-by-side code changes report for "troubleshooting.txt": 5.15_vs_5.16
1 Link: Contents Up Index: Charles Cazabon's Software
3 getmail documentation
5 This is the documentation for getmail version 5. Version 5 includes
6 numerous changes from version 3.x; if you are using getmail version 3,
7 please refer to the documentation included with that version of the
10 getmail is Copyright © 1998-2021 Charles Cazabon.
12 getmail is licensed under the GNU General Public License version 2 (only).
13 If you wish to obtain a license to distribute getmail under other terms,
14 please contact me directly.
16 Note that this license allows you to "fork" getmail. If you do so, please
17 follow open-source/free-software best practices and rename your fork so
18 the package name and executable name do not contain the word "getmail" or
19 anything confusing similar. This helps prevent users mistakenly contacting
20 the wrong people for help. The fork must also remain under the GPLv2
21 license, and must preserve all existing copyright notices in the code and
24 Troubleshooting problems
26 If you have suggestions for additions or changes to this documentation,
27 please send them to the mailing list or me.
29 I get Unicode- or UTF-8-related errors when I run getmail
31 This is almost certainly not getmail. Run getmail --version. If the
32 reported version is 6.x.x, then you are not actually running getmail; you
33 have "getmail6", which is a hostile (and license-violating) fork of
34 getmail and which contains bugs introduced by its maintainer.
36 Remove the "getmail6" package from your system. It may have been
37 introduced silently by an OS upgrade. Then install the latest version of
38 getmail from my website.
40 Error messages
42 getmail may output various diagnostic error messages. The common ones and
43 their meanings are given below.
45 ImportError: getmail version 5 requires Python version 2.3.3 or later
47 You tried to run getmail 5 with a version of Python prior to Python 2.3.3.
48 This is unsupported. If you cannot install a newer Python alongside your
49 current version, please use getmail version 3, which supports Python 1.5.2
50 and later.
52 Configuration error: …
54 getmail detected an error in your configuration. Check your getmail rc
55 file(s). getmail will do its best to point out the exact cause of the
56 error. Some of the specific errors it may find include the following.
58 Configuration error: missing required configuration parameter name
60 A class object in your getmail rc file requires the parameter name, but it
61 was not found in the appropriate section of the file.
63 Configuration error: configuration value name (value) not of required type
64 type (why)
66 The configuration parameter name must be of type type, but the supplied
67 value value does not appear to be of that type. Further information may be
68 present in why.
70 The getmail documentation contains descriptions of the syntax for each
71 parameter type.
73 Configuration error: maildir path missing trailing /
75 Maildir paths must start with dot or slash and end with a slash.
77 Configuration error: not a maildir (path)
79 The specified maildir path path does not appear to be a valid maildir.
80 Check to ensure that it is a valid maildir, and that getmail has
81 permission to write to it.
83 Configuration error: ... (path: maildir subdirectory "path" does not exist)
85 The specified maildir path path does not appear to be a valid maildir, as
86 it is missing one of the required subdirectories. Check to ensure that it
87 is a valid maildir and that getmail has permission to write to it.
89 Configuration error: not an mboxrd file (path)
91 The specified mboxrd path path does not appear to be a valid mboxrd file.
92 To avoid corrupting files in the event of a user typo, getmail will not
93 deliver messages to files that do not appear to be valid mboxrd files.
95 Configuration error: mboxrd does not exist
97 The specified mboxrd does not exist. getmail will not create mbox files;
98 ensure they exist before trying to deliver to them.
100 Configuration error: the fieldname header field does not record the envelope
101 recipient address
103 In a multidrop retriever configuration, you specified that the envelope
104 recipient was recorded in a header field that getmail knows does not
105 actually record that information.
107 Configuration error: refuse to invoke external commands as root or GID 0 by
110 By default, getmail will not invoke external commands (in destinations or
111 filters) when it is running with root privileges, for security reasons.
112 See the documenation for possible solutions.
114 Configuration error: no such command path
116 An external command was specified as being located at path path, but the
117 command executable was not found at that location.
119 Configuration error: path not executable
121 A specified external command at path path was found to not be an
122 executable file.
124 Configuration error: destination specifies section name section which does
125 not exist
127 A destination in the getmail rc file refers to another rc file section
128 named section, but that section was not found in the file.
130 Retrieval error …
132 getmail detected an error while trying to retrieve a message. Some of the
133 specific errors it may find include the following.
135 Retrieval error: server … is broken; …
137 The server claimed to have a particular message, but when getmail tried to
138 retrieve it, the server returned an empty response in violation of the POP
139 or IMAP protocol. getmail will skip on to the next message.
141 This problem is almost always with an MSExchange server, and is due to
142 bugs in MSExchange. Delete the offending message from the mailbox via the
143 webmail interface if you don't want to see this error message, and report
144 the bug to the server administrator or Microsoft.
146 Delivery error …
148 getmail detected an error after retrieving a message but before delivery
149 was successfully completed. Some of the specific errors it may find
150 include the following.
152 Delivery error: maildir delivery process failed (refuse to deliver mail as
155 getmail will not deliver to a maildir as the root user. You may specify an
156 alternate user to deliver as with the user directive in the destination
157 section of your getmailrc file, or let getmail default to the user who is
158 the owner of the maildir.
160 Delivery error: mbox delivery process failed (refuse to deliver mail as
163 getmail will not deliver to an mbox file as the root user. You may specify
164 an alternate user to deliver as with the user directive in the destination
165 section of your getmailrc file, or let getmail default to the user who is
166 the owner of the mbox file.
168 Delivery error: mbox delivery process failed (not an mboxrd file)
170 The specified mbox file does not appear to be a valid mbox file.
172 Error: …
174 getmail detected an operational error. getmail will do its best to point
175 out the exact cause of the error. Common causes are failures to connect to
176 a remote mail server, timeouts during network operations, and other
177 transient failures.
179 Error: server-info does not uniquely identify messages …
181 The POP3 server for this particular account was not able to uniquely
182 identify the messages in the mailstore. You can use the
183 BrokenUIDLPOP3Retriever class with this server instead, but functionality
184 is limited because of the inability to identify messages properly.
186 Error: server-info failed to identify message X in UIDL output …
188 The POP3 server for this particular account completely failed to identify
189 one of the messages in the mailstore when the UIDL command was issued. The
190 POP server is in violation of the POP3 protocol, and getmail has no way to
191 identify the message in question.
193 The most common cause of this is servers that use the contents of the
194 Message-ID: header field as the UIDL value for the message - some messages
195 (usually spam) lack a Message-ID: header field entirely, causing these
196 servers to emit blank UIDL values for these messages, which is not
197 permitted by the POP3 protocol. You may be able to work around the problem
198 by deleting the problematic message(s) from the mailstore by other means
199 (such as a webmail interface provided by your POP3 mailhost).
201 Otherwise, you'll need to either ask the postmaster of the POP3 mail host
202 to fix the POP3 software they're using. In the meantime, you can use the
203 BrokenUIDLPOP3Retriever class with this server instead, but functionality
204 is limited because of the inability to identify messages properly.
206 Python(…) malloc: *** mmap(…) failed (…)
208 … followed by an Unhandled exception block and then MemoryError.
210 getmail ran out of memory, usually due to a bug in Python's IMAP library
211 which was fixed in early 2008.
213 If you are using IMAP and run into this problem retrieving messages that
214 aren't hundreds of megabytes in size, you can almost certainly fix it by
215 upgrading your Python installation to the latest 2.5.x or 2.6.x release.
216 Note that if you switch from Python 2.5.x to Python 2.6.x, you'll need to
217 re-install getmail with python setup.py install from the getmail source
220 Warning messages
222 getmail may output various diagnostic warning messages. The common ones
223 and their meanings are given below.
225 Warning: …
227 getmail detected a condition which might be problematic. Some of the
228 specific warnings it may find include the following.
230 Warning: ignoring unknown parameter "parameter_name"
232 A getmail rc file contained an unknown parameter. This usually indicates
233 that you've put the parameter in the wrong section of the file (such as
234 putting the read_all parameter in the [retriever] section instead of in
235 the [options] section).
237 Warning: filter filter returned fewer headers (X) than supplied (Y)
239 A message filter appeared to incorrectly remove header fields from the
240 header of a message which it handled. getmail warns you about this so that
241 you can check your filter for proper operation. Filters should add
242 information to the message header or leave it alone; check the
243 configuration for the filter program you are using.
245 Unexpected Behaviour
247 If getmail is behaving in a manner other that you expected, see the
248 following sections.
250 getmail uses the wrong hostname for my machine
252 If getmail records a hostname other than the "right" one for your host (in
253 its Received: trace header fields), check your /etc/hosts file and make
254 sure the "right" name is the first hostname listed for any of the
255 addresses of the machine.
257 getmail puts "unknown" in the Delivered-To: or Return-Path:header field
259 getmail records the envelope recipient address in the Delivered-To: header
260 field, and the envelope sender in the Return-Path: header field. If this
261 information is not available (because you're not using a multidrop
262 retriever class, or the MTA on the POP/IMAP server is broken, for
263 example), getmail uses the string "unknown". You can disable the creation
264 of the Delivered-To: header field if you wish.
266 getmail isn't replacing my command argument "%(recipient)" with the message
267 recipient address
269 The %(recipient), %(local), and %(domain) replacement strings are only
270 replaced if the message is retrieved with a multidrop retriever class;
271 otherwise, getmail does not "know" the recipient address of the message,
272 and therefore cannot perform this replacement.
274 getmail seems to take longer than expected to initialize
276 If getmail takes more than a few seconds to initialize, run the following
277 command to test:
279 python -c "import socket; print socket.getfqdn()"
281 If this seems to take a similarly long period of time to complete, the
282 delay is in finding the fully-qualified hostname of your system. The fix
283 is to ensure you have a valid mapping of address-to-hostname for all the
284 addresses in your system. You can do this in your /etc/hosts file, in your
285 authoritative content DNS server, or in another system-specific manner —
286 please contact your OS vendor (or its public support mailing list) for