"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.