Troubleshooting problems in portal and portlet applications

Portal Troubleshooting

+
Search Tips | Advanced Search

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
A portal project that is created with WebSphere Portal V6.1.0.0 on WAS V6.0 does not have a stub target runtime environment. The WebSphere Portal V6.1.0.1 project on the WAS V6.1 runtime server is an extension of the WebSphere Portal V6.1.0.0 project. The default installation of WebSphere Portal V6.1.0.1 over WAS V6.1 is a fix pack update, for which a new runtime environment is not required. The WebSphere Portal V6.1.0.1 project with WAS V7.0 is a new runtime environment.
If you create a new project with portal server v6.1.0.0, then the project can be deployed and run successfully on WebSphere Portal V6.1.0.1 with WAS V6.1, but not on WebSphere Portal V6.1.0.0 server. To resolve this problem, use Rational Application Developer V7.5.1 to import the server configuration before running a V6.1.0.0 portal project. Use the XML configuration interface to import a portal site configuration, and optionally retrieve files that are in the Web application directory. Before you create a new portal project, retrieve the server configuration files:

Select

File | Import.

On the Select page, click Portal for your import source; and then click Next.
On the Import Portal Project page, select the portal server that you want to use. If the server dialog box is empty, click New to define a server.
In the Portal project combination box, either select the name of the portal project or enter a name for the portal project to import.
Under Import Options, select whether you want to import the configuration and files, or only the configuration. If you choose to import both the configuration and files, the files under the Web application directory are imported including the JSP, CSS, and image files for themes and skins.

Optional: If you are importing an existing portal project, select the
Delete project on overwrite check box if you want to delete the existing project and all of its artifacts before you overwrite them.

For more information on defining a Portal server for import, see Importing portal sites. After importing the server configuration, you can create a WebSphere Portal V6.1.0.0 project with WebSphere Portal V6.1 on the WAS V6.0 stub, by selecting the portal server v6.1.0.0 and WebSphere Portal V6.1 on WAS V6.1 as target runtime environment.
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

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:

From the Project Explorer view, highlight the project and select Properties.
In the left pane, select Java Build Path.
In the right pane, select the Libraries tab.
Add the referenced JAR.
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..
workbench_install_directory/runtimes/portal_v5X/shared/app
...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

In the Project Explorer, expand the Enterprise Applications node.

Right-click on your portlet project EAR node. From 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:
cd workbench_installdir
rationalsdp.exe -data workspace_directory
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:

Correct the syntax of the DOCTYPE entry in the web.xml file.

Repackage the WAR file.

Import the WAR file.

If you have already imported the WAR file, follow these steps to correct the problem:

Fix the DOCTYPE entry in the Web deployment descriptor by following these steps:

In the Project Explorer view, double-click the Web deployment descriptor for the portlet project. The Web deployment descriptor editor opens.

On the
Source tab, correct the syntax of the DOCTYPE entry.

Click
Ctrl + s to save the change.

Change the
Target server for the portlet project and the EAR project by following these steps:

In the Project Explorer view, highlight the portlet project. Right-click and select
Properties. The Properties dialog box appears.

In the left panel, highlight
Server.

On the right panel, change the target
Target runtime to a WebSphere Portal server. Click OK.

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:

Import the portal project

Delete pages in the portal project

Deploy or export the portal project

Create page(s) with identical unique names in the portal project

Deploy or export the portal project

Scenario 2:

Import the portal project

Delete pages on the WebSphere Portal server

Deploy or export the portal project back to the WebSphere Portal server

Scenario 3:

Import the portal project

Delete pages on the WebSphere Portal server

Import the portal project again, without selecting the
Delete project on overwrite option.

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.
See Delayed cleanup of deleted portal pages
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 Known issues and restrictions with cooperative portlets.
For instructions on defining an alternative Web browser, see Defining Web browsers and device emulators.
Portal projects with wires between IBM® portlet API portlets fail to deploy or export to WebSphere Portal 5.1.0.0.
Refer to the deployment prerequisite instructions in Wiring portlets.
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:

Open the Portal Configuration with the default text editor.

Remove the registration handle parameter from portal configuration.

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>

Problems	Solutions
A portal project that is created with WebSphere Portal V6.1.0.0 on WAS V6.0 does not have a stub target runtime environment.	The WebSphere Portal V6.1.0.1 project on the WAS V6.1 runtime server is an extension of the WebSphere Portal V6.1.0.0 project. The default installation of WebSphere Portal V6.1.0.1 over WAS V6.1 is a fix pack update, for which a new runtime environment is not required. The WebSphere Portal V6.1.0.1 project with WAS V7.0 is a new runtime environment. If you create a new project with portal server v6.1.0.0, then the project can be deployed and run successfully on WebSphere Portal V6.1.0.1 with WAS V6.1, but not on WebSphere Portal V6.1.0.0 server. To resolve this problem, use Rational Application Developer V7.5.1 to import the server configuration before running a V6.1.0.0 portal project. Use the XML configuration interface to import a portal site configuration, and optionally retrieve files that are in the Web application directory. Before you create a new portal project, retrieve the server configuration files: Select File \| Import. On the Select page, click Portal for your import source; and then click Next. On the Import Portal Project page, select the portal server that you want to use. If the server dialog box is empty, click New to define a server. In the Portal project combination box, either select the name of the portal project or enter a name for the portal project to import. Under Import Options, select whether you want to import the configuration and files, or only the configuration. If you choose to import both the configuration and files, the files under the Web application directory are imported including the JSP, CSS, and image files for themes and skins. Optional: If you are importing an existing portal project, select the Delete project on overwrite check box if you want to delete the existing project and all of its artifacts before you overwrite them. For more information on defining a Portal server for import, see Importing portal sites. After importing the server configuration, you can create a WebSphere Portal V6.1.0.0 project with WebSphere Portal V6.1 on the WAS V6.0 stub, by selecting the portal server v6.1.0.0 and WebSphere Portal V6.1 on WAS V6.1 as target runtime environment.
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 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: From the Project Explorer view, highlight the project and select Properties. In the left pane, select Java Build Path. In the right pane, select the Libraries tab. Add the referenced JAR. 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.. workbench_install_directory/runtimes/portal_v5X/shared/app ...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 In the Project Explorer, expand the Enterprise Applications node. Right-click on your portlet project EAR node. From 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: cd workbench_installdir rationalsdp.exe -data workspace_directory 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: Correct the syntax of the DOCTYPE entry in the web.xml file. Repackage the WAR file. Import the WAR file. If you have already imported the WAR file, follow these steps to correct the problem: Fix the DOCTYPE entry in the Web deployment descriptor by following these steps: In the Project Explorer view, double-click the Web deployment descriptor for the portlet project. The Web deployment descriptor editor opens. On the Source tab, correct the syntax of the DOCTYPE entry. Click Ctrl + s to save the change. Change the Target server for the portlet project and the EAR project by following these steps: In the Project Explorer view, highlight the portlet project. Right-click and select Properties. The Properties dialog box appears. In the left panel, highlight Server. On the right panel, change the target Target runtime to a WebSphere Portal server. Click OK. 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: Import the portal project Delete pages in the portal project Deploy or export the portal project Create page(s) with identical unique names in the portal project Deploy or export the portal project Scenario 2: Import the portal project Delete pages on the WebSphere Portal server Deploy or export the portal project back to the WebSphere Portal server Scenario 3: Import the portal project Delete pages on the WebSphere Portal server Import the portal project again, without selecting the Delete project on overwrite option. 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. See Delayed cleanup of deleted portal pages
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 Known issues and restrictions with cooperative portlets. For instructions on defining an alternative Web browser, see Defining Web browsers and device emulators.
Portal projects with wires between IBM® portlet API portlets fail to deploy or export to WebSphere Portal 5.1.0.0.	Refer to the deployment prerequisite instructions in Wiring portlets.
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: Open the Portal Configuration with the default text editor. Remove the registration handle parameter from portal configuration. 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>