                     Known problems and solutions
                     ============================

    This document presents some problems that people may stumble onto
    when installing Gnatsweb:

    1. When I run 'make test ...', the connect test fails, and I get a
       messy error message like this:

       ----------------------------------------------------------------
       perl test.pl
       Content-type: text/html

       <H1>Software error:</H1>
       <CODE>Can't call method &quot;header&quot; on an undefined value at
       gnatsweb.pl line 2215, &lt;SOCK&gt; line 1.
       </CODE>
       <P>
       For help, please send mail to this site's webmaster, giving
       this error message and the time and date of the error.

       [Tue Oct  9 11:12:21 2001] test.pl: Can't call method "header" on an
       undefined value at gnatsweb.pl line 2215, <SOCK> line 1.
       connect...........................................FAIL
       make: *** [test] Error 29
       ----------------------------------------------------------------

       This message means that Gnatsweb is unable to connect to the
       GNATS server.  The problem lies either in the
       password/username/database combination you supplied to
       'make test' or with the GNATS server itself.  Try the following:

       - Read item 6 of the INSTALL document carefully.  Check that
         you gave an existing username, password and database
         combination.
       - As item 6 says, check that you have an /etc/gnats-db.conf
         file and carefully check the syntax of the entries in this
         file.
       - GNATS may be denying access to the machine which the
         webserver runs on.  Read item 2 of the INSTALL document
         carefully.  There have also been instances where the GNATS
         server machine has had a hosts.deny file in the /etc
         directory, denying access no matter what GNATS has been set
         up to provide.  If this is the case, consult your system
         administrator.
       - If your are still unable to get the test script to connect,
         try telneting from your web server to port 1529 of the GNATS
         server and see if your connection is being accepted.  If you
         can connect by telnet, you should as a last resort try to do
         a 'make install' of Gnatsweb and see if it works even though
         the tests failed.


    2. The attachment handling functionality in the Create PR and Edit
       PR screens is missing.

       The Base64 Perl module is probably missing from your system.
       See item 4 in the INSTALL document on how to fix this.


    3. Email is going to the wrong place, e.g. to 'joe' instead
       of 'joe@my.org'.

       Fix all the email addresses in
       $GNATS_ROOT/gnats-adm/responsible.


    4. Using Lynx for Gnatsweb login is broken.

       No good solution exists at the present time.  We believe that
       current versions of Lynx have some broken cookie/redirect
       functionality which causes this.


    5. When you use the "Remember this query as" function, the query
       is stored as a cookie in your web browser. If the query is very complex,
       the resulting cookie might become larger than the limit imposed by
       the web server on cookie transfers. The following error will be
       issued by the web server when you try to access the GNATS database:

       Bad Request

       Your browser sent a request that this server could not understand.

       Size of a request header field exceeds server limit.

       Solution 1: A quick client-side solution is to delete the offending
       cookie from the repository of your browser (cookies.txt in Netscape, the
       cookies directory in the Windows user profile for Internet Explorer).

       Solution 2: A more permanent solution is the server-side one. If you use
       Apache, recompile and install it with the DEFAULT_LIMIT_REQUEST_FIELDSIZE
       setting in src/include/httpd.h of the Apache source tree increased from
       the default value of 8190 to something like 32768.


    6. Getting help.

       - Go through the TROUBLESHOOTING document.
       - Try sifting through the GNATS-related mailing list archives
         at http://sources.redhat.com/ml/
       - If you still have problems, try posting to the gnats-devel or
         bug-gnats mailing lists.  How to subscribe is covered at
         http://sources.redhat.com/gnats/.  Please avoid posting until
         you are completely certain that there is nothing relevant in
         the mailinglist archives.
