{=
  include("docs.util");
  start_docs_page(docs.technical_manual.page_titles.troubleshooting);
=}
<p><b>You should consult 
this page when something goes wrong with the installation or use of $(PRODUCT_NAME).</b></p>


<h3>$PRODUCT_NAME doesn't run properly when I try to run/launch it...</h3>
On Windows and MacOS, this should never happen; double-clicking $PRODUCT_NAME, or running it from the Start menu,
should bring up a window with the $PRODUCT_NAME logo and login.  If it doesn't, please contact
us at <a href=mailto:$SUPPORT_EMAIL>$SUPPORT_EMAIL</a>,
so we can investigate it.<p>

On UNIX, this can be the major initial obstacle to using $(PRODUCT_NAME).  There are dozens of types 
of UNIX out there, and often several variants of each type.  Since $PRODUCT_NAME is a 
binary compiled program, 
it will only run on a system similar to the one it was built on. 
We have attempted the difficult task of building $PRODUCT_NAME on as many different systems as possible, 
to ensure that it runs on the vast majority of customers' machines, but it is a difficult 
task due to the great variety available.<p>

To start, you need to find a version of $PRODUCT_NAME 
with a hardware architecture and operating system which matches yours.  For instance, 
if you're running Linux on an x86/Pentium system, you need to download the version of $PRODUCT_NAME 
for x86/Linux.  The x86/FreeBSD version won't work, and neither will the Alpha/Linux version.
If there are several versions of $PRODUCT_NAME which seem to approximately match your setup, 
try them <i>all</i> -- keep running them until one of them works.
Remember that you have to gunzip and untar them before you can use them -- see {=docs_chapter_link('installation')=}.
If possible, run them from the command line (e.g. using ssh or telnet) first, even if you intend to 
run them as CGI -- there are a lot fewer things that can go wrong with a command-line run, so 
you'll know right away if it doesn't work.  If none of them work when run from the command line (via ssh or telnet), 
please contact us at <a href=mailto:$SUPPORT_EMAIL>$SUPPORT_EMAIL</a>, so we can 
help you get $PRODUCT_NAME running.<p>

If you can't run $PRODUCT_NAME from the command line (i.e. if you have only FTP access to your server), 
you can still use it.  You'll need to gunzip it and untar it somewhere else (gunzip and untar 
programs are available for all platforms), and then upload the <code>$PRODUCT_EXECUTABLE_DOCS</code> binary program (the large 
file in the resulting $lang_stats.directory) and the LogAnalysisInfo directory
in <i>binary</i> mode to your cgi-bin $(lang_stats.directory).
Change it to readable and executable by "all" or "world"
using your ftp client (using chmod or whatever your ftp client uses 
to change permissions).
If possible, change your cgi-bin $lang_stats.directory to world writable temporarily during the $PRODUCT_NAME install; 
it makes the install simpler.  Some servers won't allow that, so if you have problems, change it back 
to world read-only and try again.  In any event, you should change it back to read-only after installation.
Once the binary is there and ready to run, try running it from a web browser, using the 
appropriate URL for your server, it's often something like http://www.myserver.com/cgi-bin/$PRODUCT_EXECUTABLE_DOCS.
If you get an error, try looking in your web server's error log, if one is available, to see what 
went wrong.  If it simply didn't run, or crashed, and if there's another version available for 
your platform, try that version instead.  If none of the versions work, please contact us at 
<a href=mailto:$SUPPORT_EMAIL>$SUPPORT_EMAIL</a>.<p>


<h3>The web browser crashes...</h3>
<p>It is important to distinguish this problem from "$PRODUCT_NAME crashes" listed below.
If you are using $PRODUCT_NAME through a web browser, and the one displaying the $PRODUCT_NAME menu disappears,
then it is your web browser that has crashed, not $(PRODUCT_NAME).
This is usually caused by a bug in your web browser -- make sure you are running the latest
version of your browser.</p>

<h3>$PRODUCT_NAME crashes...</h3>
Verify that it was really $PRODUCT_NAME, 
and not your web browser, that crashed. 
The most common cause of crashes is when $PRODUCT_NAME runs out of memory while building a database.  Try 
watching $PRODUCT_NAME's memory usage while it is processing, to see if it is consuming all available memory. Change the memory usage by using <code>top</code> on UNIX, or 
the Process Manager on Windows, or the About This Computer window on MacOS. 

$PRODUCT_NAME will often generate an error when it runs out of memory, but due to 
technical reasons, this is not always possible, and sometimes running out of 
memory can cause $PRODUCT_NAME to crash.  See <b>$PRODUCT_NAME runs out of memory</b>, below, 
for suggestions on limiting $PRODUCT_NAME's memory usage.<p> 

Barring out-of-memory problems, $PRODUCT_NAME should never crash; if it does, 
it is probably a significant bug in $(PRODUCT_NAME).  We do our best to ensure that $PRODUCT_NAME is bug-free, 
but all software has bugs, including $(PRODUCT_NAME).  If $PRODUCT_NAME is crashing on your computer, 
we would like to hear about it -- please send email to
<a href=mailto:$SUPPORT_EMAIL>$SUPPORT_EMAIL</a>,
describing the type of computer you are using and the circumstances surrounding the crash.
We will track down the cause of the crash, fix it, and send you a fixed version of $(PRODUCT_NAME).<p>

<h3>$PRODUCT_NAME runs out of memory...</h3>
$PRODUCT_NAME can use a lot of memory when it processes large amounts of data.
If there is not enough memory available for $PRODUCT_NAME to perform the task you have 
requested, it will generate an error message, reporting that it could not allocate 
as much memory as it needed, and it will stop doing whatever it was doing.<p>

One way to fix this problem is to increase the amount of memory available to $(PRODUCT_NAME).
On Windows and MacOS, there is usually no operating-system memory restriction on $PRODUCT_NAME,
but if you're using a shared server, there may be one -- if you find $PRODUCT_NAME is running 
out of memory or crashing immediately when used, check with your server administrator to see
if there are any restrictions on memory usage.
On UNIX, you can increase the amount of memory 
available to individual processes; how this is done varies, but try the <code>limit</code> 
command.  On any platform, you can add more physical memory, or increase the amount of
virtual memory, to let $PRODUCT_NAME have more memory to work with.<p> 

<p>For additional installation-related troubleshooting tips, see the end of the {=docs_chapter_link('installation')=} chapter,
and the Troubleshooting section of the <a href="?dp+docs.faq.index">FAQ</a>.</p>

<p>See {=docs_chapter_link('resources')=} for a discussion of memory 
usage, disk usage, processing time, and how they relate to each other.</p>

{= end_docs_page() =}