Handbook:Server Operation:Troubleshooting

When troubleshooting problems, it is important to take a look at the logs. See hylafax-log(5F) for specific error message information. It may also be prudent to turn up ServerTracing or SessionTracing in the config file. For SessionTracing, 0xFFF would be the normal debugging value.

There exists an incompatibility between some versions of HylaFAX with some versions of libtiff. It cannot be overstated that unpatched HylaFAX versions 4.1beta2 and earlier will only work with libtiff versions 3.4 and earlier. The symptoms of this incompatibility problem are varied and widespread throughout HylaFAX functions and can be misleading. HylaFAX versions 4.1beta3 and later support both libtiff versions 3.4 and 3.5 when compiled from source. Keep in mind that HylaFAX binaries (RedHat RPMs, for example) of CVS versions between 4.1beta2 and 4.1beta3 are compatible only with libtiff 3.4 or 3.5, depending on the release. In general, follow the dependency requirements. Libtiff 3.5.5 has significant improvements, including some that are of particular interest to fax page layout, and it is recommended that libtiff-3.5.5 or newer be used when possible.

The libtiff 3.6.1 release contained a serious flaw with respect to writing CCITT G3 and G4 TIFF (fax) image formats. Unpatched (see: http://bugs.hylafax.org/bugzilla/show_bug.cgi?id=500), this version of libtiff cannot be used for fax use.

Installation Errors
A common question arising during faxsetup is in relation to these messages:

Warning: /bin/vgetty does not exist or is not an executable program! Warning: /bin/egetty does not exist or is not an executable program!

Simply put, don't worry about them. Both of these programs have to do with data and voice call handling, and for the purposes of faxing, their presence is unnecessary.

Server Status Errors
If faxstat says, Running and idle but no fax in the send-queue is faxed, then likely:


 * faxgetty is not running
 * the modem config file is wrong
 * your libtiff version doesn't agree with your HylaFAX version

If '/usr/local/sbin/hylafax start' results in:

HylaFAX: not started (script disabled by configure).

Then your system is not likely configured for SysV init scripts such as this hylafax script, and the most straight-forward method of getting hfaxd and faxq running is to start them in an rc.local startup script "manually".

Faxing Errors
If you're using mail-to-fax gateway and mails remain in /var/spool/mqeue and get continuously re-sent, then you're probably experiencing an old HylaFAX and sendmail bug that has been fixed. Update to current versions of both.

If sendfax errors with "localhost: unknown host", make sure that your /etc/hosts file is configured properly for the loopback. It should have a line like this:

127.0.0.1      localhost       loopback

Even under the best circumstances, faxing errors may never get fewer than about 1% unless the recipient fax machine types are fixed. Some fax machines have peculiar methods of communication. However, it is the goal of HylaFAX development to make HylaFAX flexible enough to communicate with any sane fax machine, and so such problems could rightly be considered HylaFAX bugs. For the sake of working around this problem, you may want to try using a different faxmodem or different faxmodem configuration settings. In particular, it can be useful to shift your faxmodem from functioning in Class 2/2.0 to Class 1 or vice-versa. To do this, re-run faxaddmodem.

Some of these types of errors will appear in the logs as:


 * Unspecified Transmit Phase B error
 * No response to MPS repeated 3 times
 * RSPREC error/got DCN
 * No answer (T.30 T1 timeout)
 * DCS sent 3 times without response
 * Client does not support...

If you can reproduce an error such as this, it would be a good idea to report it along with a portion of your session log to the hylafax-users mailing list for analysis.

HylaFAX Status Codes
See: HylaFAX_Status_Codes

Development & Reporting Bugs - Bugzilla
HylaFAX development is controlled by CVS, and code development is the major topic on the hylafax-devel mailing list. CVS read-access is open to all, however, write access is not. Unless you're doing a large amount of coding, it is suggested that you post proposed patches and explanations of them on the hylafax-devel mailing list for average development work. See http://www.hylafax.org/cvs.html for better HylaFAX CVS information.

If you are confident that a problem you are experiencing is a HylaFAX bug you may want to report it on the hylafax-users or hylafax-devel mailing list to confirm this. Reveiwing the archives would also be advisable. HylaFAX development and bug control is also handled by Bugzilla. You can also submit bug reports and patches there: http://bugs.hylafax.org/bugzilla/.

Selected Mailing List Posts
Chances are good that if you're having trouble with something in HylaFAX that somebody else has already had that problem. And chances are also good that the issue has been discussed on one of the mailing lists or at some other place. Here are a number of commonly referred-to and useful mailing-list archives and web-links. Be aware that some of this information may refer to specific HylaFAX versions; context is important; watch the dates!

  Modem-Related Problems http://www.hylafax.org/archive/2000-06/msg00206.html http://www.hylafax.org/class1.html http://www.hylafax.org/archive/2000-08/msg00522.html http://www.hylafax.org/archive/2000-08/msg00534.html http://www.hylafax.org/archive/2000-08/msg00538.html http://www.hylafax.org/archive/2001-04/msg00336.html   Mass Faxing or General Fax Sending Errors http://www.hylafax.org/archive/2000-06/msg00016.html http://www.hylafax.org/archive/2000-08/msg00344.html http://www.hylafax.org/archive/2000-08/msg00183.html http://www.hylafax.org/archive/2001-01/msg00328.html http://www.hylafax.org/archive/2001-11/msg00164.html </LI>  Fax Viewing</B> http://www.hylafax.org/archive/2000-08/msg00081.html </LI>  Source Patches and Other Useful Tidbits</B> http://www.hylafax.org/patches/ http://www.hylafax.org/archive/2000-08/msg00271.html http://www.hylafax.org/archive/2000-08/msg00504.html http://www.hylafax.org/archive/2005-05/msg00075.html </LI>  HylaFAX Functions and Features</B> http://www.hylafax.org/HylaFAQ/Q230.html http://www.hylafax.org/archive/1999-08/msg00228.html <BR>http://www.hylafax.org/archive/2000-11/msg00182.html <BR>http://bugs.hylafax.org/bugzilla/show_bug.cgi?id=96 </LI> <LI> <B>SuSE Linux Specific Information</B> <BR>http://www.hylafax.org/archive/2000-05/msg00193.html <BR>http://www.hylafax.org/archive/2000-07/msg00300.html <BR>http://www.hylafax.org/archive/2000-06/msg00208.html </LI> </UL>

Some Common Problems and Solutions
<UL> <LI> <BR> <BR><B>Solution:</B> http://www.hylafax.org/archive/2000-11/msg00133.html <BR><B>Solution:</B> http://www.hylafax.org/archive/2000-12/msg00190.html </LI> <LI> Ghostscript - <BR><B>Solution:</B> http://www.hylafax.org/archive/2002-03/msg00323.html </LI> <LI> " " is sent to the modem, which returns an " " <BR><B>Solution:</B> http://www.hylafax.org/archive/2000-11/msg00151.html </LI> <LI> Faxcover template files, faxcover.ps, which worked on older versions don't work with 4.1beta2 <BR><B>Solution:</B> http://bugs.hylafax.org/bugzilla/show_bug.cgi?id=81 </LI> <LI> <BR><B>Solution:</B> http://www.hylafax.org/archive/2000-08/msg00390.html </LI> <LI> faxgetty interferes with internet dialer <BR><B>Solution:</B> http://www.hylafax.org/archive/2000-11/msg00137.html </LI> <LI> received faxes are not saved in TIFF G3 format <BR><B>Solution:</B> http://www.hylafax.org/archive/1997-11/msg00300.html <BR><B>Solution:</B> http://www.hylafax.org/archive/2000-08/msg00205.html </LI> <LI> faxmail does not process non-US-ASCII characters properly <BR><B>Solution:</B> http://www.hylafax.org/archive/2000-11/msg00110.html </LI> <LI> A hardware PCI modem won't work with HylaFAX... <BR><B>Solution:</B> http://www.hylafax.org/archive/2000-12/msg00115.html </LI> <LI> <BR><B>Solution:</B> http://www.hylafax.org/archive/2000-12/msg00208.html </LI> <LI> <BR><B>Solution:</B> http://www.hylafax.org/archive/2001-01/msg00130.html </LI> <LI> Many fax jobs are queued, but not all get sent <BR><B>Solution:</B> http://www.hylafax.org/archive/2001-01/msg00255.html </LI> <LI> I can't generate a correctly encrypted password for etc/hosts.hfaxd <BR><B>Solution:</B> http://www.hylafax.org/archive/2001-01/msg00282.html </LI> <LI> root can't remove faxes from the queue <BR><B>Solution:</B> http://www.hylafax.org/archive/2001-02/msg00066.html </LI> <LI> <BR><B>Solution:</B> http://www.hylafax.org/archive/2001-04/msg00423.html </LI> <LI> <BR><B>Solution:</B> http://www.hylafax.org/archive/2001-03/msg00234.html </LI> <LI> <BR><B>Explanation:</B> http://www.hylafax.org/archive/2001-05/msg00016.html </LI> </UL>