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.

If the Mathematica kernel cannot run, this is a fatal error for your server. There are two common causes for this.

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.

This is only an issue for running webMathematica under 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.

vncviewer :1

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.

This is only an issue for running webMathematica under the X Window System.

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.

xwd  -display :1 -root | xwud

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.

su tomcat -c "/usr/X11R6/bin/Xvfb :1 -screen 0 800x600x24 "&

The command to run the server with a bit depth of 16 follows.

su tomcat -c "/usr/X11R6/bin/Xvfb :1 -screen 0 800x600x16 "&

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 typeset images are failing, then you should confirm that the front end is properly configured.

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.

<KernelInitializeCode>
Developer`UseFrontEnd[Needs[ "MyApplication`"]]
</KernelInitializeCode>

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.createMathLinkGuts(Unknown=Source)
at com.wolfram.jlink.MathLinkFactory.createMathLink(Unknown=Source)
at com.wolfram.jlink.MathLinkFactory.createKernelLinkGuts(Unknown Source)
at com.wolfram.jlink.MathLinkFactory.createKernelLink(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.

If you find that webMathematica does not work, you may notice in the servlet log that JLink` has not been loaded.

Error:: Mathematica cannot load JLink`.
    Check that the JLink Mathematica application has been
    installed as described in the JLink documentation.

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.

If you find that webMathematica does not work, you may notice in the servlet log a report of a NoClassDefFoundError exception for TryCatchFinally.

500 Internal Server Error
/webMathematica/Examples/Hello.jsp:

javax/servlet/jsp/tagext/TryCatchFinally
java.lang.NoClassDefFoundError: javax/servlet/jsp/tagext/TryCatchFinally
at java.lang.ClassLoader.defineClass0(Native Method)
at java.lang.ClassLoader.defineClass(ClassLoader.java:509)
at java.lang.ClassLoader.defineClass(ClassLoader.java:438)

This error is found when the webMathematica custom JSP tags are used on older servlet containers that do not support the JSP 1.2 API.

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 NoClassDefFoundError exception. An example is shown below.

java.lang.NoClassDefFoundError: com/wolfram/jlink/MathLinkException
           at java.lang.Class.newInstance0(Native Method)
           at java.lang.Class.newInstance(Class.java:237)

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.

java.lang.NoSuchMethodError at com.wolfram.kerneltools.KernelData.startInit(Unknown Source) at com.wolfram.kerneltools.KernelPool.initKernels(Unknown Source) at com.wolfram.kerneltools.KernelPoolManager.acquireKernelPool(Unknown Source) 

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.