This section describes a number of specific problems you might find when installing or running webMathematica. In addition to this section, you may wish to look at the sections on Logging and the Kernel Monitor, as well as the section on Debugging webMathematica.
A first cause is that the Mathematica installation cannot be found; this might happen if you installed Mathematica in a non-standard location. You can resolve this by setting the KernelExecutable parameter in MSPConfiguration.xml; this is discussed in detail in Installing the webMathematica Web Application.
A second cause is that Mathematica cannot find its license and so cannot run. You can test for this with the Check Mathematica test.
Certain operations require the Mathematica front end, for example, the rendering of typeset images and graphics or the use of any Mathematica notebook API functions. If you are running on a Unix machine and using the X Window System, make sure you have studied the section on Configuring for the X Window System.
As described in the section on installation, it is typical to run a virtual frame buffer X server, Xvnc, to run the Mathematica front end. If this does not seem to be running correctly (e.g. graphics do not work), you can query the running of the frame buffer by using the vncviewer utility.
You will need to enter the password for the Xvnc server, and then you will see a view of the screen that the server provides. You should see the Mathematica front end running. If there are any problems, you may see dialog boxes describing the problems.
Xvfb is a virtual frame buffer X server that can run the Mathematica front end. If it does not seem to be running correctly (e.g. graphics do not work), you can query the running of the frame buffer by using the xwd utility.
Under certain configurations, this can be very slow. You can improve the performance by modifying the bit depth of the virtual server, for example, from 24 to 16. The following will run the server with bit depth of 24.
If you find that pages that should hold images, such as the plotting examples, do not actually show any pictures, you should check the logging system; problems will be recorded here.
If you find that you have problems using functions from Mathematica packages or applications, then study the section on Mathematica Packages and Applications. A problem may occur if you try to use code that does not use the Mathematica package format, since the postprocessing code for each request will remove any symbols in the default context.
If you make definitions for symbols that are in the default context with the KernelInitializeCode configuration setting, they will be cleared and the symbols removed by the postprocessing code for each request. This also applies to packages that are loaded from the KernelInitializeCode and that are not written in the Mathematica package format to make proper use of contexts. Any definitions must use their own context for names. You can do this by prepending the name with a context (for example TestNameSpace`Compute) or by making appropriate use of BeginPackage and EndPackage.
Another point about the use of the KernelInitializeCode parameter is that certain packages may require the front end in order to be initialized correctly. You can load these packages into webMathematica with Developer`UseFrontEnd; this is shown below.
If you find that formatted output has vertical text (such as superscript, subscripts, or fractions) that does not line up, the problem may be that you are formatting into a text-based output and not using a fixed-width font. The text-based formatting requires a fixed-width font for vertical alignment.
You can confirm that your computations are failing to complete, due to the request timing out by inspecting the log system. In this case you should first check the computations. Perhaps there is some problem in the code being executed that causes it to take longer than anticipated. To check this, you could try to run the input in a normal session of Mathematica. If you think the code is running correctly, you could try to increase the KernelTimeLimit configuration parameter.
If you find that webMathematica does not work, you may notice an UnsatisfiedLinkError exception in the log files.
Exception in thread "main" java.lang.UnsatisfiedLinkError:MLOpen
at com.wolfram.jlink.NativeLink.MLOpen(Native Method)
at com.wolfram.jlink.NativeLink.<<init>(Unknown Source)
at com.wolfram.jlink.MathLinkFactory.createKernelLinkGuts(Unknown Source)
This means that J/Link is not installed correctly, specifically that the dynamic library has not been located by the Java system. This library is typically called libJLinkNativeLibrary.so on Unix, JLinkNativeLibrary.dll on Windows, and libJLinkNativeLibrary.jnilib on Mac OS X. Certain servlet containers will not load native libraries from inside a web application. In this case, you should copy SystemFiles from WEB-INF/lib into a general directory and modify the JLinkNativeLibraryDirectory configuration parameter. Many servlet containers, such as Tomcat, can load native libraries from inside a web application. For these, the version of J/Link inside webMathematica should work. If you see this problem you should contact support for assistance.
This means that you did not install J/Link correctly, specifically that the Mathematica application J/Link has not been located by Mathematica. Since webMathematica contains its own version of J/Link, this problem should not be observed, and you should contact support for assistance.
500 Internal Server Error
at java.lang.ClassLoader.defineClass0(Native Method)
This means that J/Link is not installed correctly; specifically the J/Link Java archive has not been located by the Java system. This archive is called JLink.jar. Since webMathematica contains its own version of J/Link, this problem should not be observed, and you should contact support for assistance.
If you find that webMathematica does not work, you may notice in the initial web page or in the servlet log a report of a NoSuchMethodError exception that is generated inside of the startInit method of the KernelData class. An example is shown below.
This will occur if you try to run webMathematica with an older version of J/Link. This can happen if, at some time in the past, a copy of JLink.jar was installed directly into the Java runtime. In general, it is not a good idea to install classes into your Java runtime, because these classes will always be loaded even if a newer version is made available, as happens with this error. The solution is to search in your copy of Java for JLink.jar and remove it. You should also search for and remove the native library JLinkNativeLibrary, which is often found in the SystemFiles directory. webMathematica has its own copy of J/Link and there is no need to install J/Link into the Java runtime.