1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<!--
docs/COPYING 2a + DRY: https://github.com/getmail6/getmail6
Please refer to the git history regarding who changed what and when in this file.
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="content-type" content="application/xhtml+xml;charset=iso-8859-1" />
<title>getmail troubleshooting (version 6)</title>
<meta name="author" content="Charles Cazabon and others" />
<meta name="description" content="Troubleshooting instructions for getmail version 5" />
<meta name="keywords" content="getmail troubleshooting, getmail 6 troubleshooting, getmail6 troubleshooting, getmail6, POP3, IMAP, SSL, domain mailbox, multidrop, fetchmail replacement, message filtering, maildir, mboxrd, MDA" />
<link rel="Contents Up Index" title="getmail6" href="../" />
<style type="text/css" media="all">@import "getmaildocs.css";</style>
<style type="text/css" media="all">@import "/style/styles.css";</style>
</head>
<body id="top">
<div class="content">
<!----><h1 id="title">getmail documentation</h1>
<p class="introduction">
This is the documentation for getmail version 6,
a port of getmail version 5 to python 3 without adding features.
</p>
<p class="about">
getmail6 is Copyright © 1998-2025 by Charles Cazabon and others:<br>
<charlesc-getmail @ pyropus.ca><br>
<roland.puntaier @ gmail.com>
</p>
<p class="about">
getmail and getmail6 are licensed under the
<a href="COPYING">GNU General Public License version 2</a> (only).
</p>
<h1 id="toc">Table of Contents</h1>
<ul>
<li><a href="documentation.html">getmail documentation</a></li>
<li>
<ul>
<li><a href="documentation.html#title">getmail documentation</a></li>
<li>
<ul>
<li><a href="documentation.html#features">Features</a></li>
<li><a href="documentation.html#requirements">Requirements</a></li>
<li><a href="documentation.html#obtaining">Obtaining getmail</a></li>
<li><a href="documentation.html#installing">Installing getmail</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="configuration.html">getmail configuration</a></li>
<li>
<ul>
<li><a href="configuration.html#configuring">Configuring getmail</a></li>
<li>
<ul>
<li><a href="configuration.html#rcfile">Creating a getmail rc file</a></li>
</ul>
</li>
<li><a href="configuration.html#running">Running getmail</a></li>
<li>
<ul>
<li><a href="configuration.html#running-commandline-options">Commandline options</a></li>
<li><a href="configuration.html#running-mda">Using getmail as an MDA</a></li>
<li><a href="configuration.html#running-fetch">Using getmail_fetch to retrieve mail from scripts</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="troubleshooting.html">getmail troubleshooting</a></li>
<li>
<ul>
<li><a href="troubleshooting.html#troubleshooting">Troubleshooting problems</a></li>
<li>
<ul>
<li><a href="troubleshooting.html#error-messages">Error messages</a></li>
<li>
<ul>
<li><a href="troubleshooting.html#errmsg-pyversion">ImportError: getmail version 6.xy requires Python version 2.7.18 or later</a></li>
<li><a href="troubleshooting.html#errmsg-config">Configuration error: …</a></li>
<li>
<ul>
<li><a href="troubleshooting.html#errmsg-config-missing-parameter">Configuration error: missing required configuration parameter <span class="meta">name</span></a></li>
<li><a href="troubleshooting.html#errmsg-config-parameter-wrong-type">Configuration error: configuration value <span class="meta">name</span> (<span class="meta">value</span>) not of required type <span class="meta">type</span> (<span class="meta">why</span>)</a></li>
<li><a href="troubleshooting.html#errmsg-config-maildir-slash">Configuration error: maildir path missing trailing /</a></li>
<li><a href="troubleshooting.html#errmsg-config-maildir-not">Configuration error: not a maildir (<span class="meta">path</span>)</a></li>
<li><a href="troubleshooting.html#errmsg-config-maildir-not2">Configuration error: ... (path: maildir subdirectory "<span class="meta">path</span>" does not exist)</a></li>
<li><a href="troubleshooting.html#errmsg-config-mboxrd-not">Configuration error: not an mboxrd file (<span class="meta">path</span>)</a></li>
<li><a href="troubleshooting.html#errmsg-config-mboxrd-missing">Configuration error: mboxrd does not exist</a></li>
<li><a href="troubleshooting.html#errmsg-config-envelope-recipient">Configuration error: the <span class="meta">fieldname</span> header field does not record the envelope recipient address</a></li>
<li><a href="troubleshooting.html#errmsg-config-root-commands">Configuration error: refuse to invoke external commands as root or GID 0 by default</a></li>
<li><a href="troubleshooting.html#errmsg-config-no-command">Configuration error: no such command <span class="meta">path</span></a></li>
<li><a href="troubleshooting.html#errmsg-config-command-not-executable">Configuration error: <span class="meta">path</span> not executable</a></li>
<li><a href="troubleshooting.html#errmsg-config-missing-section">Configuration error: destination specifies section name <span class="meta">section</span> which does not exist</a></li>
</ul>
</li>
<li><a href="troubleshooting.html#errmsg-retrieval">Retrieval error …</a></li>
<li>
<ul>
<li><a href="troubleshooting.html#errmsg-retrieval-missing">Retrieval error: server … is broken; …</a></li>
</ul>
</li>
<li><a href="troubleshooting.html#errmsg-delivery">Delivery error …</a></li>
<li>
<ul>
<li><a href="troubleshooting.html#errmsg-delivery-root-maildir">Delivery error: maildir delivery process failed (refuse to deliver mail as root)</a></li>
<li><a href="troubleshooting.html#errmsg-delivery-root-mbox">Delivery error: mbox delivery process failed (refuse to deliver mail as root)</a></li>
<li><a href="troubleshooting.html#errmsg-delivery-not-mbox">Delivery error: mbox delivery process failed (not an mboxrd file)</a></li>
</ul>
</li>
<li><a href="troubleshooting.html#errmsg-operation-">Error: …</a></li>
<li>
<ul>
<li><a href="troubleshooting.html#errmsg-operation-notunique">Error: <span class="meta">server-info</span> does not uniquely identify messages …</a></li>
<li><a href="troubleshooting.html#errmsg-operation-uidlbroken">Error: <span class="meta">server-info</span> failed to identify message <span class="meta">X</span> in UIDL output …</a></li>
<li><a href="troubleshooting.html#errmsg-imapbug-memory">Python(…) malloc: *** mmap(…) failed (…)</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="troubleshooting.html#warning-messages">Warning messages</a></li>
<li>
<ul>
<li><a href="troubleshooting.html#warnmsg">Warning: …</a></li>
<li>
<ul>
<li><a href="troubleshooting.html#warnmsg-unknown-parameter">Warning: ignoring unknown parameter "<span class="meta">parameter_name</span>"</a></li>
<li><a href="troubleshooting.html#warnmsg-filterheaders">Warning: filter <span class="meta">filter</span> returned fewer headers (X) than supplied (Y)</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="troubleshooting.html#unexpected-behaviour">Unexpected Behaviour</a></li>
<li>
<ul>
<li><a href="troubleshooting.html#unexpected-hostname">getmail uses the wrong hostname for my machine</a></li>
<li><a href="troubleshooting.html#unexpected-unknown">getmail puts "unknown" in the <span class="file">Delivered-To:</span> or <span class="file">Return-Path:</span>header field</a></li>
<li><a href="troubleshooting.html#unexpected-recipient">getmail isn't replacing my command argument "%(recipient)" with the message recipient address</a></li>
<li><a href="troubleshooting.html#unexpected-slow-startup">getmail seems to take longer than expected to initialize</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="faq.html">getmail frequently-asked questions (FAQs) (version 5)</a></li>
<li>
<ul>
<li><a href="faq.html#faq">Frequently-Asked Questions (FAQs)</a></li>
<li>
<ul>
<li><a href="faq.html#faq-about">About getmail</a></li>
<li><a href="faq.html#faq-configuring">Configuring getmail</a></li>
<li><a href="faq.html#faq-how">How do I …</a></li>
<li><a href="faq.html#faq-integrating">Using getmail with other software</a></li>
<li><a href="faq.html#faq-notabug">I think I found this bug in getmail …</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h1 id="troubleshooting">Troubleshooting problems</h1>
<p>
If you have suggestions for additions or changes to this documentation, please
send them to us or open an issue on GitHub.
</p>
<!-- ********************************************************************** -->
<h2 id="error-messages">Error messages</h2>
<p>
getmail may output various diagnostic error messages. The common ones and
their meanings are given below.
</p>
<!-- ********************************************************************** -->
<h3 id="errmsg-pyversion" class="errmsg">ImportError: getmail version 6.xy requires Python version 2.7.18 or later</h3>
<p>
You tried to run getmail with a version of Python prior to Python 2.7.18
This is unsupported. If you cannot install a newer Python alongside your
current version, please use getmail version 5.
Since 2025 no Python2 version is supported any more.
</p>
<!-- ********************************************************************** -->
<h3 id="errmsg-config" class="errmsg">Configuration error: …</h3>
<p>
getmail detected an error in your configuration. Check your getmail rc
file(s). getmail will do its best to point out the exact cause of the
error. Some of the specific errors it may find include the following.
</p>
<h4 id="errmsg-config-missing-parameter" class="errmsg">Configuration error: missing required configuration parameter <span class="meta">name</span></h4>
<p>
A class object in your getmail rc file requires the parameter
<span class="meta">name</span>,
but it was not found in the appropriate section of the file.
</p>
<h4 id="errmsg-config-parameter-wrong-type" class="errmsg">Configuration error: configuration value <span class="meta">name</span> (<span class="meta">value</span>) not of required type <span class="meta">type</span> (<span class="meta">why</span>)</h4>
<p>
The configuration parameter
<span class="meta">name</span>
must be of type
<span class="meta">type</span>,
but the supplied value
<span class="meta">value</span>
does not appear to be of that type. Further information may be present in
<span class="meta">why</span>.
</p>
<p>
The getmail documentation contains
<a href="configuration.html#parametertypes">descriptions of the syntax for each parameter type</a>.
</p>
<h4 id="errmsg-config-maildir-slash" class="errmsg">Configuration error: maildir path missing trailing /</h4>
<p>
Maildir paths must start with dot or slash and end with a slash.
</p>
<h4 id="errmsg-config-maildir-not" class="errmsg">Configuration error: not a maildir (<span class="meta">path</span>)</h4>
<p>
The specified maildir path
<span class="meta">path</span>
does not appear to be a valid maildir. Check to ensure that it is a valid
maildir, and that getmail has permission to write to it.
</p>
<h4 id="errmsg-config-maildir-not2" class="errmsg">Configuration error: ... (path: maildir subdirectory "<span class="meta">path</span>" does not exist)</h4>
<p>
The specified maildir path
<span class="meta">path</span>
does not appear to be a valid maildir, as it is missing one of the required
subdirectories. Check to ensure that it is a valid
<a href="http://cr.yp.to/proto/maildir.html">maildir</a>
and that getmail has permission to write to it.
</p>
<h4 id="errmsg-config-mboxrd-not" class="errmsg">Configuration error: not an mboxrd file (<span class="meta">path</span>)</h4>
<p>
The specified mboxrd path
<span class="meta">path</span>
does not appear to be a valid mboxrd file. To avoid corrupting files in
the event of a user typo, getmail will not deliver messages to files that
do not appear to be valid mboxrd files.
</p>
<h4 id="errmsg-config-mboxrd-missing" class="errmsg">Configuration error: mboxrd does not exist</h4>
<p>
The specified mboxrd does not exist. getmail will not create mbox files;
ensure they exist before trying to deliver to them.
</p>
<h4 id="errmsg-config-envelope-recipient" class="errmsg">Configuration error: the <span class="meta">fieldname</span> header field does not record the envelope recipient address</h4>
<p>
In a multidrop retriever configuration, you specified that the envelope
recipient was recorded in a header field that getmail knows does not
actually record that information.
</p>
<h4 id="errmsg-config-root-commands" class="errmsg">Configuration error: refuse to invoke external commands as root or GID 0 by default</h4>
<p>
By default, getmail will not invoke external commands (in destinations or
filters) when it is running with root privileges, for security reasons.
See the documentation for possible solutions.
</p>
<h4 id="errmsg-config-no-command" class="errmsg">Configuration error: no such command <span class="meta">path</span></h4>
<p>
An external command was specified as being located at path
<span class="meta">path</span>,
but the command executable was not found at that location.
</p>
<h4 id="errmsg-config-command-not-executable" class="errmsg">Configuration error: <span class="meta">path</span> not executable</h4>
<p>
A specified external command at path
<span class="meta">path</span>
was found to not be an executable file.
</p>
<h4 id="errmsg-config-missing-section" class="errmsg">Configuration error: destination specifies section name <span class="meta">section</span> which does not exist</h4>
<p>
A destination in the getmail rc file refers to another rc file section named
<span class="meta">section</span>,
but that section was not found in the file.
</p>
<!-- ********************************************************************** -->
<h3 id="errmsg-retrieval" class="errmsg">Retrieval error …</h3>
<p>
getmail detected an error while trying to retrieve a message.
Some of the specific errors it may find include the following.
</p>
<h4 id="errmsg-retrieval-missing" class="errmsg">Retrieval error: server … is broken; …</h4>
<p>
The server claimed to have a particular message, but when getmail tried to
retrieve it, the server returned an empty response in violation of the
POP or IMAP protocol. getmail will skip on to the next message.
</p>
<p>
This problem is almost always with an MSExchange server, and is due
to bugs in MSExchange. Delete the offending message from the mailbox
via the webmail interface if you don't want to see this error message,
and report the bug to the server administrator or Microsoft.
</p>
<!-- ********************************************************************** -->
<h3 id="errmsg-delivery" class="errmsg">Delivery error …</h3>
<p>
getmail detected an error after retrieving a message but before delivery was
successfully completed.
Some of the specific errors it may find include the following.
</p>
<h4 id="errmsg-delivery-root-maildir" class="errmsg">Delivery error: maildir delivery process failed (refuse to deliver mail as root)</h4>
<p>
getmail will not deliver to a maildir as the root user. You may specify an
alternate user to deliver as with the
<span class="file">user</span>
directive in the destination section of your
<span class="file">getmailrc</span>
file, or let getmail default to the user who is the owner of the maildir.
</p>
<h4 id="errmsg-delivery-root-mbox" class="errmsg">Delivery error: mbox delivery process failed (refuse to deliver mail as root)</h4>
<p>
getmail will not deliver to an mbox file as the root user. You may specify
an alternate user to deliver as with the
<span class="file">user</span>
directive in the destination section of your
<span class="file">getmailrc</span>
file, or let getmail default to the user who is the owner of the mbox file.
</p>
<h4 id="errmsg-delivery-not-mbox" class="errmsg">Delivery error: mbox delivery process failed (not an mboxrd file)</h4>
<p>
The specified mbox file does not appear to be a valid mbox file.
</p>
<!-- ********************************************************************** -->
<h3 id="errmsg-operation-" class="errmsg">Error: …</h3>
<p>
getmail detected an operational error. getmail will do its best to point
out the exact cause of the error. Common causes are failures to connect
to a remote mail server, timeouts during network operations, and other
transient failures.
</p>
<h4 id="errmsg-operation-notunique" class="errmsg">Error: <span class="meta">server-info</span> does not uniquely identify messages …</h4>
<p>
The POP3 server for this particular account was not able to uniquely identify
the messages in the mailstore. You can use the
<span class="file">BrokenUIDLPOP3Retriever</span> class with this server instead,
but functionality is limited because of the inability to identify messages
properly.
</p>
<h4 id="errmsg-operation-uidlbroken" class="errmsg">Error: <span class="meta">server-info</span> failed to identify message <span class="meta">X</span> in UIDL output …</h4>
<p>
The POP3 server for this particular account completely failed to identify
one of the messages in the mailstore when the UIDL command was issued.
The POP server is in violation of the POP3 protocol, and getmail has no way
to identify the message in question.
</p>
<p>
The most common cause of this is servers that use the contents of the
Message-ID: header field as the UIDL value for the message - some messages
(usually spam) lack a Message-ID: header field entirely, causing these
servers to emit blank UIDL values for these messages, which is not
permitted by the POP3 protocol. You may be able to work around the problem
by deleting the problematic message(s) from the mailstore by other means
(such as a webmail interface provided by your POP3 mailhost).
</p>
<p>
Otherwise, you'll need to either ask the postmaster of the POP3 mail host
to fix the POP3 software they're using. In the meantime, you can use the
<span class="file">BrokenUIDLPOP3Retriever</span> class with this server
instead, but functionality is limited because of the inability to identify
messages properly.
</p>
<h4 id="errmsg-imapbug-memory" class="errmsg">Python(…) malloc: *** mmap(…) failed (…)</h4>
<p>
… followed by an <span class="file">Unhandled exception</span> block
and then <span class="file">MemoryError</span>.
</p>
<p>
getmail ran out of memory.
</p>
<p>
If you are using IMAP and run into this problem retrieving messages that
aren't hundreds of megabytes in size, you can almost certainly fix it by
upgrading your Python installation to the latest 3.* release.
</p>
<!-- ********************************************************************** -->
<h2 id="warning-messages">Warning messages</h2>
<p>
getmail may output various diagnostic warning messages. The common ones and
their meanings are given below.
</p>
<!-- ********************************************************************** -->
<h3 id="warnmsg" class="warnmsg">Warning: …</h3>
<p>
getmail detected a condition which might be problematic.
Some of the specific warnings it may find include the following.
</p>
<h4 id="warnmsg-unknown-parameter" class="warnmsg">Warning: ignoring unknown parameter "<span class="meta">parameter_name</span>"</h4>
<p>
A getmail rc file contained an unknown parameter. This usually indicates
that you've put the parameter in the wrong section of the file (such as
putting the
<span class="file">read_all</span>
parameter in the
<span class="file">[retriever]</span>
section instead of in the
<span class="file">[options]</span>
section).
</p>
<h4 id="warnmsg-filterheaders" class="warnmsg">Warning: filter <span class="meta">filter</span> returned fewer headers (X) than supplied (Y)</h4>
<p>
A
<a href="configuration.html#conf-filters">message filter</a>
appeared to incorrectly remove header fields from the header of a message
which it handled. getmail warns you about this so that you can check your
filter for proper operation. Filters should add information to the message
header or leave it alone; check the configuration for the filter program you
are using.
</p>
<!-- ********************************************************************** -->
<h2 id="unexpected-behaviour">Unexpected Behaviour</h2>
<p>
If getmail is behaving in a manner other that you expected, see the
following sections.
</p>
<h3 id="unexpected-hostname">getmail uses the wrong hostname for my machine</h3>
<p>
If getmail records a hostname other than the "right" one for
your host (in its Received: trace header fields), check your
<span class="file">/etc/hosts</span>
file and make sure the "right" name is the first hostname
listed for any of the addresses of the machine.
</p>
<h3 id="unexpected-unknown">getmail puts "unknown" in the <span class="file">Delivered-To:</span> or <span class="file">Return-Path:</span>header field</h3>
<p>
getmail records the envelope recipient address in the
<span class="file">Delivered-To:</span>
header field, and the envelope sender in the
<span class="file">Return-Path:</span>
header field. If this information is not available (because you're not
using a multidrop retriever class, or the MTA on the POP/IMAP server is
broken, for example), getmail uses the string "unknown". You can
disable the creation of the
<span class="file">Delivered-To:</span>
header field if you wish.
</p>
<h3 id="unexpected-recipient">getmail isn't replacing my command argument "%(recipient)" with the message recipient address</h3>
<p>
The
<span class="file">%(recipient)</span>,
<span class="file">%(local)</span>,
and
<span class="file">%(domain)</span>
replacement strings are only replaced if the message is retrieved with
a multidrop retriever class; otherwise, getmail does not "know"
the recipient address of the message, and therefore cannot perform this
replacement.
</p>
<h3 id="unexpected-slow-startup">getmail seems to take longer than expected to initialize</h3>
<p>
If getmail takes more than a few seconds to initialize, run the following
command to test:
</p>
<pre class="example">
python -c "import socket; print socket.getfqdn()"
</pre>
<p>
If this seems to take a similarly long period of time to complete, the delay
is in finding the fully-qualified hostname of your system. The fix is to
ensure you have a valid mapping of address-to-hostname for all the addresses
in your system. You can do this in your
<span class="file">/etc/hosts</span>
file, in your authoritative content DNS server, or in another
system-specific manner — please contact your OS vendor (or its
public support mailing list) for assistance.
</p>
</div>
</body>
</html>
|
