Troubleshooting

Consult the table below for some common problems and their solutions.

Other troubleshooting resources

Refer to the readme file for Rational® tools. It is available from the Start menu (in Windows) or from the installation launchpad for the Rational Software Delivery Platform.

Problem resolution

Problems Solutions
JSP or Java™ compilation errors occur for imported, exported, or deployed portal JSP files or Java classes that rely on external JAR files for some classes may fail to compile if any of these conditions occur:
  • The JSP files or Java classes were imported from a remote Portal server and use external JAR files located in the remote server's WebSphere_install_directory/lib or Portal_server_install_directory/shared/app directories.
  • The JSP files or Java classes were exported from a Rational tools project that has access to the JAR files and installed in a remote Portal server that does not have access to the JAR files
  • The JSP files or Java classes were deployed from a Rational tools project that has access to the JAR files and the target Portal server does not have access to the JAR files

This can occur because the import, export and deploy operations do not affect the referenced JAR files.

To resolve this problem, if your Portal project uses external JAR files, the JAR files need to be made available to the server.
  • To make the JAR files available to a portal project, copy the JAR files to the development machine and add them to the Java Build Path of the portal project. To set the Java Build Path, follow these steps:
    1. From the Project Explorer view, highlight the project and select Properties.
    2. In the left pane, select Java Build Path.
    3. In the right pane, select the Libraries tab.
    4. Add the referenced JAR.
    5. Click OK to save the configuration.
  • To make the JAR files available to the WebSphere® Portal Test Environment, copy the JAR files to the development machine and add them to the workbench_install_directory/runtimes/portal_v5X/shared/app directory of the test environment server.
  • To make JAR files available to a remote Portal server, manually copy the required JAR files to the remote Portal server system after exporting or deploying the Portal project.
Portlets that contain utility *.jar files used by EJB snippet support fail at run time on a remote WebSphere portal server. This happens during when deploying these portlets as part of a new portal project to a Portal server.

For more information, refer to Testing and deploying portlets that reference J2EE modules.
Performing Run on Server on a portlet that is being used in a portal project yields an unexpected EAR file in the Server Selection dialog. Instead of selecting the portlet project, select the portlet's EAR project and right-click to perform the Run on Server function.
To find the portlet project's EAR file
  1. In the Project Explorer, expand the Enterprise Applications node.
  2. Right-click on your portlet project EAR node. Form the menu, select Run > Run on Server.
Could not restore workbench error when starting the Rational Software Delivery Platform. Restart Rational tools and specify a new directory as the workspace. If you selected Use this workspace as the default and do not show this dialog box again before and the dialog to allow you to specify the workspace directory does not appear, start the workbench with the -data parameter. From the command line:

For Windows

cd workbench_installdir
rationalsdp.exe -data workspace_directory

For Linux

cd workbench_installdir
rationalsdp.sh -data workspace_directory

where workbench_installdir is the directory where you have installed Rational Software Delivery Platform and workspace_directory is the new workspace directory you want to use
Running (testing) or debugging a portlet in the test environment failed. After launching the Run on Server or Debug on Server task, the test environment was in starting state, but it terminated. The portlet has no validation errors in JSP files or Java code, and the deployment descriptor is correct. Ensure Build automatically is selected in Workbench Preferences. To check the value, select Windows > Preferences > Workbench.
Portlet deployment or testing on a remote system failed. The failure can occur with any of these tasks:
  • Deploying a portlet using the Deploy wizard
  • Running or debugging a portlet project using a Server Attach server
  • Deploying a portal project which uses a portlet project
  • Running or debugging a portal project which uses portlet project
Ensure that the server is configured correctly. See Network considerations.
When importing a portlet WAR file, no WebSphere Portal servers appear in the Target server list. Check the DOCTYPE entry of the Web deployment descriptor (web.xml) in the WEB-INF directory of the WAR file. The correct syntax is: 
<!DOCTYPE web-app 
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" 
"http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">
where the string web-app_2_2.dtd defines the Web level of the WAR file. The string web-app_2_2.dtd is for Web level 2.2 ( J2EE specification level 1.2). The string web-app_2_3.dtd is for Web level 2.3 ( J2EE specification level 1.3).

A common mistake is to have a "." instead of a "_" character in the version number. For instance, web-app_2.2.dtd instead of web-app_2_2.dtd.

If you have not imported the WAR file, follow these steps to correct the problem:
  1. Correct the syntax of the DOCTYPE entry in the web.xml file.
  2. Repackage the WAR file.
  3. Import the WAR file.
If you have already imported the WAR file, follow these steps to correct the problem:
  1. Fix the DOCTYPE entry in the Web deployment descriptor by following these steps:
    1. In the Project Explorer view, double-click the Web deployment descriptor for the portlet project. The Web deployment descriptor editor opens.
    2. On the Source tab, correct the syntax of the DOCTYPE entry.
    3. Click Ctrl + s to save the change.
  2. Change the Target server for the portlet project and the EAR project by following these steps:
    1. In the Project Explorer view, highlight the portlet project. Right-click and select Properties. The Properties dialog box appears.
    2. In the left panel, highlight Server.
    3. On the right panel, change the target Target runtime to a WebSphere Portal server. Click OK.
    4. Repeat the steps above for the associated EAR project.
Portlets that contain J2EE dependencies (i.e. database connections, EJB and dependent utility JAR projects) do not deploy to a remote Portal server with either portlet or portal projects.

For more information, refer to Testing and deploying portlets that reference J2EE modules and Referring to other projects

Duplicate object ID

Deploy or export of a portal project fails. Part of the error message indicates a DuplicateKeyException for the primary key constraint defined on PAGE_INST(OID) .

When an object is deleted from a WebSphere Portal server, the object is marked as deleted but is not immediately removed. If the object is then exported or deployed to the remote portal server attach server, a duplicate object ID error can occur.

This problem can occur in the following scenarios:
  • Scenario 1:
    1. Import the portal project
    2. Delete pages in the portal project
    3. Deploy or export the portal project
    4. Create page(s) with identical unique names in the portal project
    5. Deploy or export the portal project
  • Scenario 2:
    1. Import the portal project
    2. Delete pages on the WebSphere Portal server
    3. Deploy or export the portal project back to the WebSphere Portal server
  • Scenario 3:
    1. Import the portal project
    2. Delete pages on the WebSphere Portal server
    3. Import the portal project again, without selecting the Delete project on overwrite option.
    4. Deploy or export the portal project back to the WebSphere Portal server

To resolve this problem, you can either configure WebSphere Portal to remove objects immediately, or run an individual cleanup task using the XML configuration interface. For instructions, see the Administering > Delayed cleanup of deleted portal pages section in the WebSphere Portal Product Documentation
Server connection failure when debugging on either a test environment or remote server.

If you cannot attach to a test environment or remote portal server for debugging, and you are sure that the server is properly configured, then the problem may be caused by a timeout when connecting to the JVM process on the remote machine. This can happen if the remote machine is busy or if your network is slow.

You can increase the default timeout value of three (3) for debugging by selecting Window > Preferences > Java > Debug, and increasing the value of the Debugger timeout field to ten (10) seconds.
Cooperative portlets are not performed by the built-in browser (Konqueror) of SuSE Linux Enterprise Server version 9.

For more information, including a list of Web browsers that support the cooperative portlet menus, refer to the Developing portlets > Cooperative portlets > Known issues and restrictions with cooperative portlets topic in the WebSphere Portal product documentation.

For instructions on defining an alternative Web browser, see Defining web browsers and device emulators.
When deploying a portal configuration that has a WSRP producer defined, it only resolves for WebSphere Portal. Deploying a portal configuration fails when portal configuration has WSRP producers with registration handle. To fix this problem you will need to remove the registration handle manually, following these steps:
  1. Open the Portal Configuration with the default text editor.
  2. Remove the registration handle parameter from portal configuration.
  3. Save your Portal Configuration.

The registration handle parameter in the portal configuration file will look like this:

<portal:parameter>
	<base:name>handle</base:name>
	<base:value>registration handle value is set here</base:value>
</portal:parameter>
When importing a portal configuration into the targeted portal server, the Site Designing Portlet feature of IBM Rational Application Developer for WebSphere Software version 8.0.1, to customize an IBM WebSphere Portal configuration, results in error. "com.ibm.wps.command.xml.Engine processSax EJPFB0002E: Exception occurred." The exception is thrown because the Site Designing Portlet feature is not installed on the targeted portal server. To resolve the error, uninstall the Site Designing Portlet before exporting the configuration:
  1. From the Servers view, right-click WebSphere Portal server and select Open Portal.
  2. Select Administration > Portlet Management > Web Modules.
  3. Search for SiteDesignPortletProject.war file.
  4. Click the Delete button on the right side of the SiteDesignPortletProject.war file.
Publishing of dynamic web project fails on Mac. Publishing a dynamic web project fails with javax.net.ssl.SSLHandShakeException exception, when you create a dynamic web project with WebSphere Application Server, version 8.0 runtime stub, and add a new JavaServer page to the project, create a remote server (installed on Windows machine) instance without enabling to start the server remotely.
Note: The project is published without any error from Rational Application Developer installed on a Windows machine.
 The exception thrown is a limitation with Mac operating system, restarting Rational Application Developer and publishing again, resolves the problem.
Feedback