Troubleshooting
This section describes techniques for addressing problems and errors. You should first work through the Initial Checks section, which will help track down any general problems. If this does not help, study the Specific Problems section. Further information can be obtained from the Wolfram Research support website. Finally, if you have not resolved your problem and are eligible for support, you should look at the Reporting Problems section.
Initial Checks
If you try to use a browser to connect to a Wolfram Web Engine server and it does not operate in the expected way, try the following steps.
Check the Server
Make absolutely certain that your servlet container is working correctly. If you cannot connect to the demonstration examples that come with your container, then the Wolfram Web Engine is unlikely to work. Furthermore, Wolfram Research will not be able to give more than minimal assistance until your servlet container is working.
Check the URL
If your servlet container works but the Wolfram Web Engine does not, make sure you are using a correct URL. These are case sensitive, so make sure you use capital letters in the same places as the documentation describes. For example, http://localhost:8080/webengine/Examples/Hello.jsp is the appropriate usage. Make sure that this URL is consistent with the way you connect to your servlet container. If you need to specify a port number for your servlet container, you will need to use this for the Wolfram Web Engine. For example, the default settings for direct access for Tomcat is port 8080. A URL for a different servlet container might be different. The URLs in this document are all specified for Tomcat.
If you do not specify the URL correctly, you may see a Not Found (404) error in your browser.
Check the Initial Page
If the initial page that is returned to your browser in response to a Wolfram Web Engine URL, such as http://localhost:8080/webengine/Examples/Hello.jsp, contains some other indication of an error, study it carefully. Some typical problems include configuration errors, such as failure to locate a configuration file or failure to launch the Wolfram kernel. Studying the initial page and rereading the installation instructions or looking at the specific problems listed later in this section may help to resolve the problem.
If no initial page is returned, your server is not operating. As noted above, if your server does not work, the Wolfram Web Engine cannot work.
If the initial page does not help resolve your problem, please save the page. It may be useful at some later stage.
Check the Kernel Monitor
The kernel monitor contains information on the configuration of the Wolfram Web Engine site and can also print out information if your server is misconfigured. You should be able to find the monitor via http://localhost:8080/webengine/Resources/Tools/KernelMonitor.jsp. (You may have some different URL for accessing your server.) The monitor is described in more detail in a previous section.
Check the Logging System
The logging system is a good place to start to search for information on problems.
Check the Console Shell
Some servlet containers are launched from a command line in a console shell, and this may contain relevant information on any problems.
Check the Wolfram Kernel
Run the Wolfram kernel in the same way that it is run from the servlet container. For example, under Unix, the servlet container often runs as tomcat, so this should be used to run the Wolfram kernel. Do this for both the Wolfram kernel and front end.
Under Unix, a typical command to run the Wolfram kernel as tomcat is as follows:
Here is a typical command to run the Wolfram front end as tomcat:
Under Windows, it is possible to run the Wolfram kernel and front end from the Start menu.
Running the Wolfram kernel like this will help to identify problems that may prevent the web system from launching the Wolfram kernel. One source of problems is caused by a failure to find a license to run the Wolfram kernel. You can resolve this by making sure that the valid Wolfram license is present in the Wolfram layout, probably by placing a mathpass file into $InstallationDirectory/Configuration/Licensing.
Specific Problems
This section describes a number of specific problems you might find when installing or running Wolfram Web Engine. 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 the Wolfram Web Engine.
Problems Running the Kernel
If the Wolfram kernel cannot run, this is a fatal error for your server. There are two common causes for this.
A first cause is that the Wolfram installation cannot be found; this might happen if you installed Wolfram Language in a nonstandard location. You can resolve this by setting the KernelExecutable parameter in MSPConfiguration.xml; this is discussed in detail in Installing the Wolfram Web Engine Application.
A second cause is that Wolfram Language cannot find its license and so cannot run. You can test for this with a test to check the Wolfram kernel.
Problems Running the Front End
Certain operations require the Wolfram front end—for example, the rendering of typeset images and graphics or the use of any Wolfram 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.
Problems Testing Xvnc (Unix Only)
This is only an issue for running the Wolfram Web Engine 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 Wolfram 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 Wolfram front end running. If there are any problems, you may see dialog boxes describing the problems.
Problems Testing Xvfb (Unix only)
This is only an issue for running the Wolfram Web Engine under the X Window System.
Xvfb is a virtual frame buffer X server that can run the Wolfram 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 a bit depth of 24:
The command to run the server with a bit depth of 16 follows:
Images Do Not Work
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 there.
If you find that typeset images are failing, then you should confirm that the front end is properly configured.
Wolfram Packages and Applications
If you find that you have problems using functions from Wolfram packages or applications, then study the section on Wolfram packages and applications. A problem may occur if you try to use code that does not use the Wolfram package format, since the postprocessing code for each request will remove any symbols in the default context.
Kernel Initialization
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 Wolfram 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 the Wolfram Web Engine with Developer`UseFrontEnd; this is shown here:
<KernelInitializeCode>
Developer`UseFrontEnd[Needs[ "MyApplication`"]]
</KernelInitializeCode>
Vertical Alignment in Formatting
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.
Timeout Problems
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 Wolfram Language. If you think the code is running correctly, you can try to increase the KernelTimeLimit configuration parameter.
UnsatisfiedLinkError
If you find that the Wolfram Web Engine 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 macOS. 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 the Wolfram Web Engine should work. If you see this problem, you should contact support for assistance.
Cannot Load JLink`
If you find that the Wolfram Web Engine 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 Wolfram Language application J/Link has not been located by Wolfram Language. Since the Wolfram Web Engine contains its own version of J/Link, this problem should not be observed, and you should contact support for assistance.
NoClassDefFoundError: TryCatchFinally
If you find that the Wolfram Web Engine does not work, you may notice in the servlet log a report of a NoClassDefFoundError exception for TryCatchFinally:
500 Internal Server Error
/webengine/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 Wolfram Web Engine custom JSP tags are used on older servlet containers that do not support the JSP 1.2 API.
NoClassDefFoundError: JLink Classes
If you find that the Wolfram Web Engine does not work, you may notice in the initial webpage or in the servlet log a report of a NoClassDefFoundError exception. An example is shown here:
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 the Wolfram Web Engine contains its own version of J/Link, this problem should not be observed, and you should contact support for assistance.
NoSuchMethodError: KernelData
If you find that the Wolfram Web Engine does not work, you may notice in the initial webpage 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 here:
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 the Wolfram Web Engine 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. The Wolfram Web Engine has its own copy of J/Link, and there is no need to install J/Link into the Java runtime.
Debugging the Wolfram Web Engine
The Wolfram Web Engine involves running computations inside a server. This poses a number of problems and constraints for investigating why it does not work as you intend. The best way to track down issues is to use Wolfram Workbench to connect to the server and debug your code.
Not Using Wolfram Workbench
If you do not want to use Wolfram Workbench, you can use messages and print statements to resolve your problems. You can get message output returned in your webpage with MSPGetMessages and the output of print statements with MSPGetPrintOutput. The capture of message and print output is described in the example Messages.jsp. It is probably a good idea to confirm that your calculations work correctly in an interactive Wolfram Language session.
In addition to message and print output, you can use the logging and monitor features provided by the system. These are described in more detail in the sections on logging and the kernel monitor. The simplest technique is to look at the files written by the servlet engine. A more sophisticated way is to use the monitor, which can be accessed via a URL, for example http://localhost:8080/webengine/Resources/Tools/KernelMonitor.jsp. If you increase the level of log output by setting VerboseLogs to true, you will generate more output.
Using Wolfram Workbench
You can use Wolfram Workbench to debug your Wolfram Language code as it runs in the server. With this, you can do things such as set breakpoints, examine the stack and catch messages. In this way, you can gain a deeper understanding of how your code runs, thereby helping you to develop more quickly. You can do this for code loaded into a JSP and for code that runs as a web service. For more information, see the documentation sections on debugging with Workbench.
Logging
An administrator needs to confirm correct operation of a server and track down problems as they occur. The Wolfram Web Engine helps by providing a variety of different types of logging systems.
Wolfram Web Engine Logging
The Wolfram Web Engine provides a flexible logging system that allows you to learn about the running of your server. This can be useful as a way to track down errors. The system is built on top of the popular log4j logging services. The system is configured with files loaded when the server launches and can record different levels of events: FATAL, ERROR, WARN, INFO, DEBUG and TRACE, ranging from serious to not serious.
Configuration for the Wolfram Web Engine logging system is found in the file log4j.properties, located in WolframWebEngine/WEB-INF/classes. The default provides three loggers, which collect different types of log information. By default, logging only records events that are at level INFO and above. Output for all the loggers goes into <path-to-tomcat>/logs.
| WolframWebEngine.log | core Wolfram Web Engine log file |
| KernelEvents.log | kernel events, such as evaluations, messages and print output |
| JobEvents.log | logging for jobs that support queues |
Default Wolfram Web Engine log files.
The core Wolfram Web Engine log file is the core main logger that records many different types of events. The request log file contains logging for each request and is a simple way to see activity to the site. The kernel log file shows information about how the kernel is used. In particular, it contains message output (at the WARN level) and print output (at the INFO level).
The folder WolframWebEngine/WEB-INF/classes/samples contains a sample logging configuration file, log4j.properties.DEBUG, which turns on logging at the DEBUG level. It also contains log4j.properties-samples, a logging file with more comments, and the original file, log4j.properties.BACK. To activate one of these, copy it to WolframWebEngine/WEB-INF/classes, rename it to log4j.properties and restart the server. The log files will collect information at the new level. This might be a good way to track down problems in your Wolfram Web Engine server.
To configure the logging system in more detail, you could study log4j.properties-samples; then you should probably consult one of the many references that exist for log4j.
Server Logging
One key place to search for information on problems is the server logging system. Under Tomcat, typical logging files are <path-to-tomcat>/logs/localhost_log.YYYY-MM-DD.txt, where the file name includes the date. For other servlet containers, you will need to study the relevant documentation. If the log file is empty, it may indicate that the user running the servlet container does not have permission to write to the log file directory.
The log file records serious errors; if your system does not function correctly at startup time, it would be good to look here. For example, if the configuration file is not found or the kernel cannot be launched, this will be recorded in the log file. Later, if there is a serious error that requires shutting down a kernel, this is also recorded.
Note that the server logs do not show Wolfram Web Engine–specific logging. This comes in the Wolfram Web Engine logging system.
The Kernel Monitor
The kernel monitor is a servlet that collects information on the running of your site. You should be able to find the monitor via the URL http://localhost:8080/webengine/Resources/Tools/KernelMonitor.jsp. (You may have some different URL for accessing your server.) Upon access, the monitor brings up a page showing the current status of the Wolfram Web Engine, describing various parameters of the site and giving status information for each kernel. If you look at this page, access some JSPs and then look at the page again, you should see updates, such as a change in the number of times kernels have been accessed.
For security purposes, it would be sensible to restrict access to the kernel monitor. If the servlet engine is accessed via an Apache web server, access can be restricted in the server configuration files. The section on Apache and Tomcat describes how this can be done.
Reporting Problems
If you have been unable to resolve your problem and you are eligible for support, you should prepare the following information. The more detailed the information, the easier it will be to track down the problem.
1. The version of the Wolfram Web Engine you are using
2. The version of Wolfram Language you are using
3. Your computer operating system version (e.g. Windows 7)
4. The servlet engine you are using
5. The HTTP server you are using (if applicable, e.g. Apache)
6. A one- or two-line summary of the problem, including any steps that may be necessary to reproduce it
In addition, for installation problems, the following items will be very useful:
7. A copy of the initial HTML page
This information should then be supplied with any request for support.