WebFOCUS Troubleshooting Tips

In this section:

Troubleshooting WebFOCUS considers all the places where a problem can occur. These include the following:

Top of page

General Tips

Try some of these solutions when troubleshooting WebFOCUS problems:

  1. Clear your web browser cache and close all browser instances. Often, even after you have taken steps to correct a problem, the page or pages that contained the original problem still reside in cache.
  2. Ensure that all components are started and are listening on their expected ports. The WebFOCUS web application may take some time to load.
  3. Ensure that you typed in the correct URL. WebFOCUS URLs are case-sensitive.
  4. If your web server is not listening on port 80, make sure you are calling with the correct port in the URL.
  5. Ensure that the correct application names are listed in your WebFOCUS Reporting Server APP PATH. This is defined in:

    If you receive a Resource not found message, then this may be the problem.

  6. Be aware that WebFOCUS does not support two concurrent Microsoft Internet Explorer sessions from a single PC. This is due to an Internet Explorer cookie management limitation. When you run two browser sessions simultaneously from the same machine, messages such as file not found, appear.
  7. During testing, be sure to call pages using HTTP or HTTPS requests and not by selecting Open from the File menu in the web browser.
  8. Turn on tracing through the WebFOCUS Administration Console.
  9. Clear the cache in your application server after completing the upgrade installation. For example, if you are using Apache Tomcat, the cache can be cleared by manually deleting any subdirectories that correspond to the context roots that you deployed (for example, /ibi_apps and /ibi_help), which are located in the following directory:

    Note: If installed by WebFOCUS Client, Tomcat will be installed in the root directory of the WebFOCUS installation which, by default, is c:\ibi\tomcat.

  10. In the WebFOCUS Administration Console, click Diagnostics on the left and use the available options to troubleshoot.
  11. Restart all components, especially your web or application servers.

Top of page

HTTP 500 Internal Server Message

If you receive an HTTP 500 server message on the Configuration Verification Utility page after installation, clear your browser cache and access the Diagnostics page again from either the Program Menu option or by copying the URL into another browser window. This may occur on a full installation or on a service pack upgrade.

Top of page

Web Browser Issues


If you are planning to use WebFOCUS products, note that browsers released after the production date of a WebFOCUS version are subject to certification. Certification is done with the current release level of WebFOCUS, App Studio, and Developer Studio. For additional information, see Web Browser Support for WebFOCUS, which can be accessed by clicking on the following URL:


Note: Some browsers may function differently depending on the operating system. See the WebFOCUS Release Notes for detailed information on known issues related to browser version or configuration.

Reference: Firefox Support

For information on supported Firefox browser versions, see Web Browser Support for WebFOCUS, which can be accessed by clicking on the following URL.


The following settings are required to use Firefox with Dashboard:

Top of page

JVM Support Issue with IBM WebSphere Application Server

How to:

WebFOCUS 8 requires Java VM Version 6 or higher on the system that is hosting the application server where the WebFOCUS Client web application is displayed and the ReportCaster Distribution Server is installed.

Procedure: How to Verify JVM Version

There are two methods for verifying the Java VM version installed on the machine where the WebFOCUS client is deployed.

Top of page

Web and Application Server Debugging

Ensure that your web and application servers are configured, as explained in Configuring Web and Application Servers.

WebFOCUS relies on processing by the Java VM, web server, and application server. Their debugging tools and log files can help troubleshoot common WebFOCUS issues. Review the documentation for your web and application servers for information on their tracing and log files.

Top of page

Java Memory Issues

Depending on your application server default settings, you may need to adjust the Java VM memory options if you run into performance issues. If the WebFOCUS installation configured Tomcat for you, this is done automatically.

The most common Java VM options you need to set involve the size of the Java heap and stack, which determine memory availability for Java programs and the Java VM. Errors can occur if not enough memory is available, and the heap size impacts performance, since it determines how often garbage collection occurs.

The following are the most common Java VM options related to memory settings. Replace the #### with the size you wish to set:


Sets the maximum Java heap size. It is common to make this 1/4 of the system RAM, but it must be at least 1536 MB (1.5 GB).


Sets the initial Java heap size. It is common to make this 1/8 of the system RAM, but it must be at least 1536 MB (1.5 GB).


Sets the Java thread stack size. You do not need to set this unless you are fine tuning your environment.

The size is normally set in Megabytes. For example:


To view your current Java VM memory settings, access the WebFOCUS Administration Console. In the left pane of the console, expand the Diagnostics node and click JVM Property Info, as shown in the following image.

The Java VM memory settings for your environment are displayed in the right pane, as shown in the following image.

Optimum sizes vary depending on your total memory, the needs of your application, how many other processes require memory, the type of Java VM, and other considerations. A good starting place is to set the minimum to 1/8 of the total RAM and set the maximum to 1/4 of total RAM.

Where to set these and other Java VM options depend on your application server.

Top of page

Graphics Issues

You can test basic graph functionality by running the sample cargraph.fex procedure installed with the WebFOCUS Reporting Server:


If you cannot generate graphics or want to improve performance, try adding the following Java option to your application server Java VM settings:


For Tomcat, this is in the Apache Tomcat Properties windows on the Java tab, in the Java Options field.

If you cannot run a graph request, you may also need to set NTFS permission to allow your application server full permissions to the temporary directory used by the Java VM. This directory is the java.io.tmpdir parameter that appears in the WebFOCUS Administration Console when you click Diagnostics and JVM Property Info.

Top of page

WebFOCUS Web Server Host Name and Port Settings

During the WebFOCUS Client installation, you are asked for the host name and HTTP port of your web server. This should be the host name and port that your end users use to access WebFOCUS and ReportCaster. These values are used for communications between ReportCaster and Report Library. If you use Report Library, ensure this is set to the end user accessible web server host name and port, even if it is not on the same machine as WebFOCUS and only forwards requests through a firewall.

If you need to change the web server host name and port that you entered during the installation:

  1. If you use ReportCaster, correct the host name and port number stored in the ReportCaster configuration for the Report Library. To do this, access the ReportCaster Console, which can be accessed from the WebFOCUS BI Portal. After you sign in to the WebFOCUS BI Portal, click Tools from the top menu bar and select ReportCaster Console. The ReportCaster Console opens in a new browser window. Click the Configuration tab.

    Click Report Library in the left pane and change the host name and port in the Default Library URL for Email Notification field.

    Then click the Save icon, followed by Restart to restart all WebFOCUS components.

  2. Optionally update the short cuts that appear in the Start menu for accessing WebFOCUS pages. To do this, right-click each of the following, select Properties, and adjust the host name and port that appear in the URL:

    For example:


    If you are not using ReportCaster, the ReportCaster links do not appear.

Top of page

Using the jar Utility

How to:

A jar.exe utility is installed with the Java JDK. It lets you create, extract, and edit the contents of JAR, WAR, EAR, ZIP, RAR, and other archive files. If you deploy the WebFOCUS web application as a WAR file, the jar utility lets you change the webfocus file contents.

Note: The default WebFOCUS Apache Tomcat configuration does not use the WAR file, so this utility is normally not needed with Tomcat.

Procedure: How to Ensure You Can Use the jar Utility

To use the jar command, ensure that the JAVA_HOME\bin directory is in your search PATH. For example:

C:\Program Files\Java\jdk1.8.0_45\bin

The exact directory varies depending on the Java release, and for Java 6, it is under C:\. This directory contains many Java utilities and is not added to your search PATH by the Java JDK installation. To add this to your search PATH:

  1. Go to the Windows Control Panel and open the System folder.
  2. Click the Advanced tab and click the Environment Variables button.
  3. In the bottom System variables frame, select Path.
  4. Click Edit.
  5. At the end of the line, add a semicolon and the path to the JAVA_HOME\bin directory. For example:
    ;C:\Program Files\Java\jdk1.8.0_45\bin
  6. Click OK to close out.

Procedure: How to Edit the WebFOCUS Web Application

The WebFOCUS web application is provided as both an expanded directory and a WAR file:


The easiest way to edit the web application is the following:

  1. Undeploy the webfocus.war file from your application server.
  2. Rename the webfocus.war file to webfocus-old.war. This ensures you have a back up and can keep track of where the latest version resides.
  3. Edit or add files to the expanded webfocus directory and subdirectories. You should do this even if you deploy the WAR file instead of the expanded directories. This ensures that service packs maintain your changes. When you apply a service pack, any changes must be in the expanded directories to be maintained.
  4. Open a Command Prompt.
  5. Navigate to the webfocus directory. For example:
  6. Use the jar command to create a new webfocus.war file that contains the contents of the webfocus directory and sub-directories. For example:
    jar cvf ../webfocus.war *

    This creates a webfocus.war file containing all files and subdirectories in your current directory. The webfocus.war file will be located one directory above your current location because you prefaced it with "../".

  7. Redeploy the WebFOCUS web application to your application server.

Procedure: How to Execute the jar Utility

The options for using the jar commands are useful to know. You execute the jar utility from the Command Prompt.

Top of page

WebFOCUS File Extensions

How to:

WebFOCUS files have several non-standard file extensions on Windows, such as .mas, .prf, .acx, .wfs, .cfg, and .xmls files. Depending on the software installed on your machine, these file extensions may already be in use for other applications. Normally, this causes no conflicts when using either WebFOCUS or the other applications. However, should you attempt to open a WebFOCUS file that is mapped for another application by double-clicking it in My Computer or Windows Explorer, problems can arise.

Note: By default, you might not see file extensions in My Computer or Windows Explorer. To see extensions, open My Computer or Windows Explorer. Then click the Tools menu and then Folder Options. On the View tab, deselect Hide file extensions for known file types and click OK.

Specific instances where WebFOCUS extensions may conflict are the following:

Procedure: How to Change File Type Mappings for WebFOCUS

When you open a file in My Computer or Windows Explorer, Windows opens it in the default application for which its extension is mapped. This mapping does not prevent you from opening a file using a different application than the one to which it is mapped. Therefore, changing this mapping is only required if you open WebFOCUS files from My Computer or Windows Explorer.

You can change mappings as follows:

  1. Open My Computer or Windows Explorer.
  2. Select the Tools menu and then Folder Options.
  3. Select the File Types tab.
  4. Scroll through the list of files types and select the extension you wish to change. For example:
  5. Click the Advanced button.

    The Edit File Type windows appears.

  6. Select New.
  7. In the Action field type:
  8. Click Browse and specify the application you wish to use for WebFOCUS files. For Notepad, browse to one of the following:
  9. Click OK.
  10. Check the Always Show Extension box.
  11. Select Edit in the list of actions.
  12. Click Set Default.
  13. Click OK.

This should not interfere in the operation of any applications, but will prevent WebFOCUS files from opening in the wrong applications.

Top of page

Missing Tomcat Context Definition Files

Symptom: The context definition files for Tomcat are being deleted periodically.

The following files will be deleted randomly:


Problem: This is a problem with Tomcat in certain environments. The exact cause of the issue is unknown.

For more details, see:


Solution: Within the Tomcat configuration (server.xml), turn off autoDeploy.

  1. Edit your Tomcat server.xml.

    On Windows, this is typically found at:


    or, if the WebFOCUS client installation installed Tomcat, it is located under

  2. Find the following section within your server.xml:
    <Host name="localhost" appBase="webapps"
    unpackWARs="true" autoDeploy="true"  
    xmlValidation="false" xmlNamespaceAware="false">

    and change autoDeploy to false:

    <Host name="localhost" appBase="webapps/localhost"
    unpackWARs="true" autoDeploy="false"  
    xmlValidation="false" xmlNamespaceAware="false">
  3. Restart Tomcat.