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

For additional installation and related troubleshooting tips, see the end of the {=docs_chapter_link('installation')=} chapter, and the Troubleshooting section of the FAQ.

$PRODUCT_NAME doesn't run properly when I try to run or launch it

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 some text. If it doesn't, please contact us at $SUPPORT_EMAIL, so we can investigate.

On UNIX, this can be the major initial obstacle to using $(PRODUCT_NAME). There are many 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 to build $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.

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 all -- 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 $SUPPORT_EMAIL, so we can help you get $PRODUCT_NAME running.

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 $PRODUCT_EXECUTABLE_DOCS binary program (the large file in the resulting $lang_stats.directory) and the LogAnalysisInfo directory in binary mode to your cgi-bin $(lang_stats.directory). Change it to readable and executable by %22all%22 or %22world%22 using your ftp client (using chmod or whatever command 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 $SUPPORT_EMAIL.

I can't "zoom in" past a certain level

If you're finding that beyond a certain depth, $PRODUCT_NAME won't let you zoom in any further, the items in the tables are no longer clickable, you probably have a limit on the depth of that field in the Database Structure Options. Edit your profile, go to the Database Structure Options, and increase the Suppress value for the field you want more detail on. Then rebuild your database and the items should become clickable.

The web browser crashes

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 web browser window, the one displaying the $PRODUCT_NAME menu, profile information or statistics 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 available of your browser.

$PRODUCT_NAME crashes

See the section above, The web browser crashes, to verify that it was really $PRODUCT_NAME, and not your web browser, which 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 (using top on UNIX, or the Process Manager on Windows, or the About This Computer window on MacOS) while it is processing, to see if it is consuming all available memory. $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 $PRODUCT_NAME runs out of memory, below, for suggestions on limiting $PRODUCT_NAME's memory usage.

With the exception of 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 $SUPPORT_EMAIL, 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.

$PRODUCT_NAME runs out of memory

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

One way to fix this problem is to increase the amount of memory available to $PRODUCT_NAME. 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.

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 limit command. See {=docs_chapter_link('resources')=} for a discussion of memory usage, disk usage, processing time, and how they relate to each other.

{= end_docs_page() =}