====== Troubleshooting ======
When using Greenstone, occasionally, things will go wrong. This page includes some common 
issues users have had, and potential solutions. If you are unable to solve your problem, 
send your questions to one of the Greenstone [[support#mailing lists]].

===== Installation =====
====cgi-bin/library not working with Linux binary install on FreeBSD====

If you try to run library from the cgi-bin directory and you get a message like
 ELF binary type "0" not known.
 ./library: Exec format error. Binary file not executable.

It may be that you need to enable compatibility with linux binaries.

  * Enable it in rc.conf:
<code>
 linux_enable="YES"
</code>

  * Install linux_base from ports
  * Run the command
<code>
 brandelf -t Linux /home/gsdl/cgi-bin/library (putting the path to your library program)
</code>

===== GLI errors =====
====GLI failed to start ====
Sometimes you run GLI and it doesn't start up: a black window appears and then disappears, and you're left wondering what just happened. At other times you get a whole sequence of error messages, none of which may be be the root problem, after which GLI fails to work.

In order to help the Greenstone team find out what went wrong, you can run GLI in debug mode, which will print out the errors as it runs.

To do so,
 
1. make sure to run GLI through a terminal instead of from Windows' Start menu, by [[old:miscellaneous_questions#how_do_i_open_a_terminal_called_dos_console_in_windows|opening a DOS prompt]].

2. Next, use your DOS prompt to Change Directory (cd) into your Greenstone installation's gli folder. For example, if your Greenstone is installed in C:\Program Files\Greenstone, you'd type the following line and hit Enter:
<code>cd "C:\Program Files\Greenstone\gli"</code>

3. Now run GLI in debug mode by typing the following:
<code>gli.bat -debug</code>
On Linux and Macs, you'd type
<code>./gli.sh -debug</code>

4. The black DOS screen will no longer flash and disappear, but will remain in the background. 
If GLI starts up momentarily, there will be several additional dialogs (error consoles) that open up alongside it.
When GLI finally fails, errors are likely to get printed to the black DOS window. If they do, copy the error messages and send them to the Greenstone mailing list.


==== GLI Build errors ====
When GLI fails mysteriously, you can try manually rebuilding a collection to let us know 
if the problem is with GLI or with the underlying building scripts.

Manually building a collection is also helpful if GLI for some reason will not rebuild a collection. See the steps below.

==== Manually (re-)building a collection ====

1. On Linux and Mac, open a terminal. On Windows you would [[http://wiki.greenstone.org/doku.php?id=old:miscellaneous_questions#how_do_i_open_a_terminal_called_dos_console_in_windows|open a DOS console]].

2. Use the terminal or DOS console to Change Directory into your Greenstone installation folder. Let's assume you have Greenstone installed in C:\Program Files\Greenstone. If so, you'd type the following line and hit Enter:
<code>cd "C:\Program Files\Greenstone"</code>
On Linux your slashes will go the other way. For example, /home/me/greenstone.

3. Now you've set your DOS Prompt to be in your Greenstone installation folder. At this point, you want to run some Greenstone scripts. Firstly, the script to set up the Greenstone environment. 
On Windows, type the following and hit Enter as usual):
<code>setup.bat</code>

On Linux and Mac, type:
<code>source setup.bash</code>

4. Now that you've set up your Greenstone's environment:

**If you're rebuilding an existing collection, skip this step** and move on to the full-rebuild step just below. 
If you want to create a new collection first, do the following:
<code>perl -S mkcol.pl COLLECTION-NAME</code>
This will create an empty collection. You need to use your file browser to copy across the files you want to gather into your collection. Do this by copying the selected files into your Greenstone installation's collect/COLLECTION-NAME/import folder.

5. To build your collection manually:
  * **EITHER: In newer versions of Greenstone** 
Type the following, substituting the name of the collection you wish to build and then hit Enter: 
<code>perl -S full-rebuild.pl COLLECTION-NAME</code>
On Linux and Mac, you can leave out the perl -S at the start.

If you want **more error reporting**, use: //perl -S full-rebuild.pl -verbosity 5 COLLECTION-NAME//

  * **OR: In older versions of Greenstone** 
You'll run the 2 scripts that perform the 2 stages of the Greenstone build operation (import and buildcollection). Type the following, substituting the name of the collection you wish to build, then hit Enter:

a. First the import phase of building a collection:
<code>perl -S import.pl COLLECTION-NAME</code>
On Linux and Mac, you can leave out the "perl -S" at the start.

If you want **more error reporting**, use: //perl -S import.pl -verbosity 5 COLLECTION-NAME//

b. Then the buildcol step:
<code>perl -S buildcol.pl COLLECTION-NAME</code>

If you want **more error reporting**, use: //perl -S buildcol.pl -verbosity 5 COLLECTION-NAME//

c. This will have generated a folder called "building" inside your collection's folder. You will need to rename it to "index" (after either deleting your old index folder or moving it out of the way). Use Windows Explorer to navigate into your Greenstone installation's collect/COLLECTION-NAME directory and to rename your collection's new "building" folder to "index". 

d. If there are any errors that appear in the terminal, [[http://wiki.greenstone.org/doku.php?id=old:miscellaneous_questions#how_do_i_copy_text_such_as_error_messages_that_are_printed_on_the_dos_console|copy and paste these errors]] into a message and mail them to the Greenstone list, while describing the problem.

6. Finally, run the Greenstone server and see if your collection looks okay.


====Windows: Documents contain no text after successful build====
Are you running Norton Anti-Virus? There are some incompatibilities between Norton and the Greenstone collection building process that cause unpredictable things to happen if you build your collection while Norton is running. Try disabling Norton and rebuilding the collection.

If you do not have Norton or disabling Norton does not solve the problem please [[http://www.greenstone.org/cgi-bin/library?e=p-en-faqbuild-utfZz-8&amp;a=p&amp;p=support|contact us]] for further help.


====Windows: Greenstone appears to crash completely after successful build====
Are you running Norton Anti-Virus? There are some incompatibilities between Norton and the 
Greenstone collection building process that cause unpredictable things to happen if you build 
your collection while Norton is running. Try disabling Norton and rebuilding the collection.

If you do not have Norton or disabling Norton does not solve the problem please 
[[http://www.greenstone.org/cgi-bin/library?e=p-en-faqbuild-utfZz-8&amp;a=p&amp;p=support|contact us]] 
for further help.

====Getting better error reporting in GLI (the Greenstone Librarian Interface)====
Sometimes, GLI runs and tries to build your collection, but something goes wrong. The build log tells you that some error occurred and your collection is left unbuilt. In cases like these, when you contact the mailing list, it is helpful to provide as much of the error information as is available. To do this, you want to increase the verbosity of the build process and error reporting.

1. In GLI, go to File > Preferences > Mode tab. Set the mode to Expert.

2. Then, turn on the verbosity for both import and building as follows:
  * In GLI's Create tab, click the "Import Options" on the left. On the right, scroll down to the Verbosity field and tick it. Then set its text field value to 5. 
  * Do the same for the "Build Options", once again on the left part of the Create tab.

3. Before rebuilding, still on the left of the Create tab, choose "Message log" to return to viewing the build output.

4. Now rebuild the collection once more and you will hopefully get more error reporting. 
Copy the relevant portions of the error output (using Ctrl+C), and paste them into a new email message (with Ctrl+V) and mail it to us.


===Error reporting when using the Mac shortcuts to run Greenstone applications===
A Mac binary comes with shortcuts (which have an invisible *.app extension) for gli, client-gli, gems and gs2-server for Greenstone 2 and gs3-server for Greenstone 3. These shortcuts will not work in Greenstone code checked out from SVN.

When you double-click these shortcuts, they launch the corresponding application. However, by launching Greenstone applications in this way, you don't get a console. If anything goes wrong, you can find error output in the *.output file corresponding to the application (e.g. client-gli.output) in ''GS3/web/logs'' or ''GS2/etc/logs-gsi''. If these folders were not writable, the *.output file would have been written to ''/tmp''.
====Windows Building error: can't spawn cmd.exe====
When building a collection in GLI on Windows, if you see an error message like the following in the build log output:
''Can't spawn "cmd.exe": No such file or directory ...''
then try the steps below. This error has been reported by some users. 
It appears to occur because ''%SystemRoot%'', an environment variable used 
in the ''%PATH%'' which evaluates to ''C:\windows'', isn't being passed in to the 
perl code from GLI. As a result, 
the PATH does not contain ''c:\windows\system32'' which contains ''cmd.exe'' used by perl 
to execute commands. However, this problem does not appear to manifest for all Windows 
users of Greenstone. 

The solution that has worked for the 2 members of the mailing list who 
reported this problem is as follows.

1. In a text editor, open the file ''gli.bat'' which is located in your Greenstone 
installation's "gli" folder

2. Near the top, just after ''set GLILANG=en'' add the following line:
''set PATH=c:\windows\systems32;%PATH%''
The above manually prefixes ''c:\windows\systems32;'' to the PATH during GLI's execution.

3. Now try running GLI and building the collection again.

====GLI's Preview Button fails to launch a web page ====
If you pressed the Preview Button in GLI and (firefox) browser launch fails with a message about not being able to launch a URL that looks almost right, except that firefox shows it to be prefixed with your GLI folder path, then you can try providing GLI with the full path to Firefox. This happened to someone working with GLI and Firefox on an Ubuntu.

  * In GLI, go to File > Preferences > Connection and set the Preview Command field to:
<code>/full/path/to/your/firefox %1</code>

  * On Linux, to find the full path to where your Firefox is installed, you'd open a terminal and run:
<code>which firefox</code>

**For example**, in my case, running the //which// command above returns: /usr/bin/firefox 

I would therefore set my Preview Command field to contain:
<code>/usr/bin/firefox %1</code>

  * Now quit GLI.
  * Restart it.
  * Try the preview button again.

===== Other =====
====Copying text printed in the terminal ====
There are times you may see error messages appearing in the DOS prompt (the black console with writing) when you are using the GLI or Greenstone server.
 You might want to ask about these error messages on the Greenstone Mailing list. To do so, 
* you can either press your keyboard's Pr(in)tScreen button to take a screenshot of the black DOS window and send in the picture, or
* you can copy the error output displayed on your DOS console and paste it into an email to the mailing list.
  * Right click somewhere on the black DOS screen, choose Mark. 
  * Then use your mouse to select (highlight) all relevant text. 
  * Once you've selected the necessary portion of text, hit Enter. (If you make a mistake at any point, you will need to right-click > Mark again before it will allow you to highlight). 
  * Hitting Enter was actually the copy operation, so now that the selected text is in your copy buffer, you can paste it anywhere (such as into an email to the Greenstone mailing list).


====WSASYSNOTREADY error====
This error might occur if you have no network connection available, so there is no
 IP address for the server. When you run the Greenstone server, in the small window
 where you can start the library select ''File->Settings'', and set the address resolution 
method to be "always use localhost" or "always use 127.0.0.1". Then (re)start the server.

Another possibility is that you are running an IIS server or another server which is using
the port listed. Try changing the port number that the local library uses (to e.g. 8080), in ''File->Settings''. 
Alternatively, try stopping the IIS server altogether and restarting the local library.

====Not Found error with long query====
This may be caused by the URL becoming too long for your web browser. Because Greenstone currently stores all state information in the URL, if you do a search for a long phrase the URL can become very long. Different browser's on different platforms have different maximum URL lengths but in general it seems that Netscape can handle longer URLs than can Microsoft Internet Explorer.

There is very little you can do to avoid this problem with the way Greenstone is currently implemented (aside from not searching for long phrases). Future versions of Greenstone may store some state information on the server rather than in the URL but this has yet to be implemented.

====XML::Parser errors====
Our Mac OS X Greenstone distributions are built on machines using Perl 5.6, and these distributions contain a few binary perl modules. These cause problems if you are using a recent version of perl like 5.8 or 5.8.1 (you can type "perl -v" from the command line to see the version).

On the Mac, our distribution contains modules for both perl 5.6 and 5.8 and the correct one should (hopefully) be installed.

A typical error message during import.pl would be:

''Uncaught exception from user code: Can't load  '/home/httpd/gsdl/perllib/cpan/auto/XML/Parser/Expat/Expat.so' for module XML::Parser::Expat:/home/httpd/gsdl/perllib/cpan/auto/XML/Parser/Expat/Expat.so: undefined symbol:PL_sv_undef at /usr/lib/perl5/5.8.0/i386-linux-thread-multi/DynaLoader.pm line 229. at /home/httpd/gsdl/perllib/cpan/XML/Parser.pm line 14
''

To remedy this, you need to remove the "gsdl/perllib/cpan/perl-5.8/XML" and "gsdl/perllib/cpan/perl-5.8/auto" directories. (For versions earlier than 2.52, remove "gsdl/perllib/cpan/XML" and "gsdl/perllib/cpan/auto".) Then you need to install the perl XML::Parser natively for your system.

On redhat or mandrake, install the .rpm named "perl-XML-Parser", on debian, install the "libxml-parser-perl" package. For other Linuxes, use your distribution's package, or you can get it from http://search.cpan.org/~msergeant/XML-Parser-2.34/.

You may also need to get Expat, available from http://sourceforge.net/projects/expat/.

An alternative solution that may work is to compile Greenstone from source code on your machine. See [[en:user_advanced:installation | this page]].


====Unable to view Applets with Java 7====
If you are trying to view the Phind Applet or another Greenstone Applet in your browser, but an error message appears that says 
''Java applications are blocked by your security settings'' 
or any of the other messages described at [[http://www.java.com/en/download/help/java_blocked.xml|Java blocked]], then on Windows you can do the following to give access:

  - Go to Windows' Control Panel > Programs > Java.
  - Go to the Security tab of the dialog that appears.
  - Edit the Exception Site List to contain the domain of the Greenstone server's host. For example, in the case of applets hosted on nzdl, the URL would look like http://www.nzdl.org. If you are using the GLI applet, then add URL of the remote Greenstone server to the Exception Site List.