"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 or
download 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
2
3 getmail documentation
4
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
8 software.
9
10 getmail is Copyright © 1998-2021 Charles Cazabon.
11
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.
15
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
22 documentation.
23
24 Troubleshooting problems
25
26 If you have suggestions for additions or changes to this documentation,
27 please send them to the mailing list or me.
28
29 I get Unicode- or UTF-8-related errors when I run getmail
30
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.
35
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.
39
40 Error messages
41
42 getmail may output various diagnostic error messages. The common ones and
43 their meanings are given below.
44
45 ImportError: getmail version 5 requires Python version 2.3.3 or later
46
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.
51
52 Configuration error: …
53
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.
57
58 Configuration error: missing required configuration parameter name
59
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.
62
63 Configuration error: configuration value name (value) not of required type
64 type (why)
65
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.
69
70 The getmail documentation contains descriptions of the syntax for each
71 parameter type.
72
73 Configuration error: maildir path missing trailing /
74
75 Maildir paths must start with dot or slash and end with a slash.
76
77 Configuration error: not a maildir (path)
78
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.
82
83 Configuration error: ... (path: maildir subdirectory "path" does not exist)
84
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.
88
89 Configuration error: not an mboxrd file (path)
90
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.
94
95 Configuration error: mboxrd does not exist
96
97 The specified mboxrd does not exist. getmail will not create mbox files;
98 ensure they exist before trying to deliver to them.
99
100 Configuration error: the fieldname header field does not record the envelope
101 recipient address
102
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.
106
107 Configuration error: refuse to invoke external commands as root or GID 0 by
108 default
109
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.
113
114 Configuration error: no such command path
115
116 An external command was specified as being located at path path, but the
117 command executable was not found at that location.
118
119 Configuration error: path not executable
120
121 A specified external command at path path was found to not be an
122 executable file.
123
124 Configuration error: destination specifies section name section which does
125 not exist
126
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.
129
130 Retrieval error …
131
132 getmail detected an error while trying to retrieve a message. Some of the
133 specific errors it may find include the following.
134
135 Retrieval error: server … is broken; …
136
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.
140
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.
145
146 Delivery error …
147
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.
151
152 Delivery error: maildir delivery process failed (refuse to deliver mail as
153 root)
154
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.
159
160 Delivery error: mbox delivery process failed (refuse to deliver mail as
161 root)
162
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.
167
168 Delivery error: mbox delivery process failed (not an mboxrd file)
169
170 The specified mbox file does not appear to be a valid mbox file.
171
172 Error: …
173
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.
178
179 Error: server-info does not uniquely identify messages …
180
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.
185
186 Error: server-info failed to identify message X in UIDL output …
187
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.
192
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).
200
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.
205
206 Python(…) malloc: *** mmap(…) failed (…)
207
208 … followed by an Unhandled exception block and then MemoryError.
209
210 getmail ran out of memory, usually due to a bug in Python's IMAP library
211 which was fixed in early 2008.
212
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
218 directory.
219
220 Warning messages
221
222 getmail may output various diagnostic warning messages. The common ones
223 and their meanings are given below.
224
225 Warning: …
226
227 getmail detected a condition which might be problematic. Some of the
228 specific warnings it may find include the following.
229
230 Warning: ignoring unknown parameter "parameter_name"
231
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).
236
237 Warning: filter filter returned fewer headers (X) than supplied (Y)
238
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.
244
245 Unexpected Behaviour
246
247 If getmail is behaving in a manner other that you expected, see the
248 following sections.
249
250 getmail uses the wrong hostname for my machine
251
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.
256
257 getmail puts "unknown" in the Delivered-To: or Return-Path:header field
258
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.
265
266 getmail isn't replacing my command argument "%(recipient)" with the message
267 recipient address
268
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.
273
274 getmail seems to take longer than expected to initialize
275
276 If getmail takes more than a few seconds to initialize, run the following
277 command to test:
278
279 python -c "import socket; print socket.getfqdn()"
280
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
287 assistance.