Troubleshooting problems in portal and portlet applications

Troubleshooting

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

Other troubleshooting resources

Refer to the readme file for Rational Developer. It is available on the installation launchpad for Rational Developer.

Problem Resolution
Problems Solutions
Cannot start WebSphere Portal Test Environment
Ensure that you have installed the WebSphere Portal Test Environment. Check the install log to verify successful installation. The install log for the WebSphere Portal 5.0 Test Environment is RAD_HOME\runtimes\portal_v50\log\wpsinstalllog.txt.
Change the server configuration: This solution only applies when WebSphere Portal V5.0 Test Environment cannot start in the debug mode. In the server configuration, make sure that the Enable hot method replace in debug mode checkbox in the Server page is selected. To do this, carry out the following steps:
In the Servers view, double-click the WebSphere Portal V5.0 Test Environment which fails to start in the debug mode in order to open its server configuration.
Select the Overview page.
Select the Enable hot method replace in debug mode checkbox.
Press Ctrl+S to save the updated server configuration.

Linux only: Change the access permission for the WebSphere Portal database: Because of a limitation of WebSphere Portal, the WebSphere Portal Test Environment is available for only one user to use. You can allow other users to use the server by turning on read, write, and execute permission for the WebSphere Portal database. To change the access permission, carry out the following:
cd /opt/PortalUTE/PortalServer/cloudscape/
chmod -R 777 wps50
Alternatively, you can change the user who is able to use the server by uninstalling and reinstalling the WebSphere Portal Test Environment.
Windows only:Verify that the Windows user is an Administrator:
You must be logged in as an Administrator. If not, login to Windows as an Administrator and run the WebSphere Portal Test Environment.

To run or debug Struts portlets, you need to enable transcoding (see Enabling transcoding) if portlets have static (non-JSP) or XML content.
To run or debug portlet projects which refer to other Java or EJB projects, see Referring to other projects.
To run or debug portlet projects which use application library files, refer to the section on Shared libraries in Configuring local servers for testing portlets.
Check the log of WebSphere Portal to determine the problem. Refer to the log file, or enable console logging, as described in Configuring local servers for testing portlets.

Cannot create a server for WebSphere Portal Test Environment.
Ensure that the WebSphere Portal Test Environment you want to use is installed. A WebSphere Portal Test Environment server can only be created when the Test Environment has been installed.
(WebSphere Portal v5.1 only) Ensure that you have configured preferences as described in Configuring the WebSphere Portal 5.1 Test 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 directories.
The JSP files or Java classes were exported from a Rational Developer project that has access to the JAR files and installed in an external Portal server that does not have access to the JAR files
The JSP files or Java classes were deployed from a Rational Developer 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,...
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 the workbench_install_directory/runtimes/portal_v5X/shared/app directory of the test environment server.
To make JAR files available to an external Portal server, manually copy the required JAR files to the external Portal server system after exporting or deploying the Portal project.

java.lang.NoClassDefFoundError in WebSphere Portal Test Environment When you test or debug a portlet application using local debugging and the portlet application needs to use library files or refer to other projects, you will need to make them available to the server. Refer to the section on Shared libraries in Configuring local servers for testing portlets or Referring to other projects.
The transcoding function does not work correctly when running or debugging portlets The transcoding function is disabled in the WebSphere Portal Test Environment by default. You need to enable it. Refer to Enabling transcoding.
Cannot launch the WML device emulator using WebSphere Portal Test Environment To run or debug portlets in a WML device emulator, you need to enable transcoding. Refer to Enabling transcoding. You also need to define your device emulator program using the instructions in Configuring Web browsers and device emulators.
Cannot run personalized portlet projects in the WebSphere Portal Test Environment To run or debug personalized portlet projects you need to use WebSphere Portal Server Attach and WebSphere Portal running on a remote server.
"Could not restore workbench" error when starting Rational Developer
Restart Rational Developer 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 RAD_HOME
rationalsdp.exe -data workspace_directory
cd RAD_HOME
rationalsdp.sh -data workspace_directory
where RAD_HOME is the directory where you have installed Rational Developer and workspace_directory is the new workspace directory you want to use
Portlets developed for WebSphere Portal 4.2 do not work correctly on WebSphere Portal 5.0 This solution works only when the portlets were developed by Portal Toolkit 5.0.2 or earlier.
Delete the /WEB-INF/tld/portlet.tld file from the portlet project or from the WAR file.

Most portlets written for WebSphere Portal Version 4.2 will run unchanged in WebSphere Portal Version 5.x. Some of the Portlet API 4.2.x are now marked as deprecated, but are still available on WebSphere Portal Version 5.x. However, the portlet.tld file is different between versions of WebSphere Portal. This file was included in portlet projects in Portal Toolkit 5.0.2 or earlier.

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 machine 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 Configuring networks for deployment.
The contents in the Console view are truncated when Running or Debugging a project on a WebSphere Portal Test Environment server. Ensure that Limit console output is not selected in Workbench Preferences. To check the value, select Window > Preferences > Run/Debug > Console.
The WebSphere Portal v5.1 Test Environment does not start when two or more JSR 168 portlet projects are associated with it. The WebSphere Portal v5.1 Test Environment fails to start when two or more JSR 168 portlet projects are associated with the server and they do not have the ID attribute on the <portlet-app> element in the portlet deployment descriptor. The same problem can occur if the ID attribute is not unique. To solve this problem, edit the portlet deployment descriptor (portlet.xml) and add an ID attribute with a unique value to the <portlet-app> element. Make the change using the Source page when editing the portlet deployment descriptor.
The deployment of a JSR 168 portlet project to a WebSphere Portal v5.0 server works only once. Using the WebSphere Portal administrative pages on the WebSphere Portal server, remove (uninstall) the JSR 168 portlets you want to deploy, apply the fix PQ92087 to your portal server, then deploy your portlets again using Rational Developer.

Problems	Solutions
Cannot start WebSphere Portal Test Environment	Ensure that you have installed the WebSphere Portal Test Environment. Check the install log to verify successful installation. The install log for the WebSphere Portal 5.0 Test Environment is RAD_HOME\runtimes\portal_v50\log\wpsinstalllog.txt. Change the server configuration: This solution only applies when WebSphere Portal V5.0 Test Environment cannot start in the debug mode. In the server configuration, make sure that the Enable hot method replace in debug mode checkbox in the Server page is selected. To do this, carry out the following steps: In the Servers view, double-click the WebSphere Portal V5.0 Test Environment which fails to start in the debug mode in order to open its server configuration. Select the Overview page. Select the Enable hot method replace in debug mode checkbox. Press Ctrl+S to save the updated server configuration. Linux only: Change the access permission for the WebSphere Portal database: Because of a limitation of WebSphere Portal, the WebSphere Portal Test Environment is available for only one user to use. You can allow other users to use the server by turning on read, write, and execute permission for the WebSphere Portal database. To change the access permission, carry out the following: cd /opt/PortalUTE/PortalServer/cloudscape/ chmod -R 777 wps50 Alternatively, you can change the user who is able to use the server by uninstalling and reinstalling the WebSphere Portal Test Environment. Windows only:Verify that the Windows user is an Administrator: You must be logged in as an Administrator. If not, login to Windows as an Administrator and run the WebSphere Portal Test Environment. To run or debug Struts portlets, you need to enable transcoding (see Enabling transcoding) if portlets have static (non-JSP) or XML content. To run or debug portlet projects which refer to other Java or EJB projects, see Referring to other projects. To run or debug portlet projects which use application library files, refer to the section on Shared libraries in Configuring local servers for testing portlets. Check the log of WebSphere Portal to determine the problem. Refer to the log file, or enable console logging, as described in Configuring local servers for testing portlets.
Cannot create a server for WebSphere Portal Test Environment.	Ensure that the WebSphere Portal Test Environment you want to use is installed. A WebSphere Portal Test Environment server can only be created when the Test Environment has been installed. (WebSphere Portal v5.1 only) Ensure that you have configured preferences as described in Configuring the WebSphere Portal 5.1 Test 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 directories. The JSP files or Java classes were exported from a Rational Developer project that has access to the JAR files and installed in an external Portal server that does not have access to the JAR files The JSP files or Java classes were deployed from a Rational Developer 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,... 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 the workbench_install_directory/runtimes/portal_v5X/shared/app directory of the test environment server. To make JAR files available to an external Portal server, manually copy the required JAR files to the external Portal server system after exporting or deploying the Portal project.
java.lang.NoClassDefFoundError in WebSphere Portal Test Environment	When you test or debug a portlet application using local debugging and the portlet application needs to use library files or refer to other projects, you will need to make them available to the server. Refer to the section on Shared libraries in Configuring local servers for testing portlets or Referring to other projects.
The transcoding function does not work correctly when running or debugging portlets	The transcoding function is disabled in the WebSphere Portal Test Environment by default. You need to enable it. Refer to Enabling transcoding.
Cannot launch the WML device emulator using WebSphere Portal Test Environment	To run or debug portlets in a WML device emulator, you need to enable transcoding. Refer to Enabling transcoding. You also need to define your device emulator program using the instructions in Configuring Web browsers and device emulators.
Cannot run personalized portlet projects in the WebSphere Portal Test Environment	To run or debug personalized portlet projects you need to use WebSphere Portal Server Attach and WebSphere Portal running on a remote server.
"Could not restore workbench" error when starting Rational Developer	Restart Rational Developer 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 RAD_HOME rationalsdp.exe -data workspace_directory cd RAD_HOME rationalsdp.sh -data workspace_directory where RAD_HOME is the directory where you have installed Rational Developer and workspace_directory is the new workspace directory you want to use
Portlets developed for WebSphere Portal 4.2 do not work correctly on WebSphere Portal 5.0	This solution works only when the portlets were developed by Portal Toolkit 5.0.2 or earlier. Delete the /WEB-INF/tld/portlet.tld file from the portlet project or from the WAR file. Most portlets written for WebSphere Portal Version 4.2 will run unchanged in WebSphere Portal Version 5.x. Some of the Portlet API 4.2.x are now marked as deprecated, but are still available on WebSphere Portal Version 5.x. However, the portlet.tld file is different between versions of WebSphere Portal. This file was included in portlet projects in Portal Toolkit 5.0.2 or earlier.
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 machine 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 Configuring networks for deployment.
The contents in the Console view are truncated when Running or Debugging a project on a WebSphere Portal Test Environment server.	Ensure that Limit console output is not selected in Workbench Preferences. To check the value, select Window > Preferences > Run/Debug > Console.
The WebSphere Portal v5.1 Test Environment does not start when two or more JSR 168 portlet projects are associated with it.	The WebSphere Portal v5.1 Test Environment fails to start when two or more JSR 168 portlet projects are associated with the server and they do not have the ID attribute on the <portlet-app> element in the portlet deployment descriptor. The same problem can occur if the ID attribute is not unique. To solve this problem, edit the portlet deployment descriptor (portlet.xml) and add an ID attribute with a unique value to the <portlet-app> element. Make the change using the Source page when editing the portlet deployment descriptor.
The deployment of a JSR 168 portlet project to a WebSphere Portal v5.0 server works only once.	Using the WebSphere Portal administrative pages on the WebSphere Portal server, remove (uninstall) the JSR 168 portlets you want to deploy, apply the fix PQ92087 to your portal server, then deploy your portlets again using Rational Developer.