Troubleshoot WebSphere Portal installation

  1. Troubleshoot Portal

  2. Troubleshoot WAS

 

General steps to perform if the installation fails

If the WebSphere Portal installation fails, follow these steps:

  1. Check the WebSphere Portal logs

  2. Ensure that the correct WAS Fix Packs and interim fixes are installed.

  3. Before using the installation program to install WebSphere Portal or any other component that requires WAS, verify that you can start and stop WAS.

 

Reinstall after a failed installation

If a product fails to install, do the following steps before you attempt to install again:

  1. Run uninstallation programs.

    If the installation failed before the uninstallation program was created, delete the installation directory and all of its contents before reinstalling the product.

  2. If the uninstallation program fails, delete the wp_root directory.

  3. Run the uninstallation program again.

  4. When you run the installation program, any irregularities in the vpd.properties file pertaining to WebSphere Portal will be corrected automatically. It is not recommended that you edit this file manually or delete it.

 

Installation fails after uninstalling a previous copy of WebSphere Portal

If the WebSphere Portal installation fails after you have uninstalled a previous copy of WebSphere Portal, ensure that no components of the WebSphere Portal remain before you attempt to install WebSphere Portal again. Do the following steps:

  1. Open the Administrative Console for WAS and verify that all of the WebSphere Portal components were removed by the previous uninstallation.

    Manually remove any of the components that remain, including...

    Enterprise application: WebSphere Portal Enterprise Application
    Application server: WebSphere Portal
    Data sources: wps50DS and wmmDS
    JDBC driver: wps50JDBC

  2. On the portal machine, delete the WebSphere Portal directory manually.

  3. Restart the installation.

 

Non ISO-8859-1 characters not supported in installation path

Install to paths containing non ISO-8859-1 characters does not work and is not currently supported. Installing WebSphere Portal to use an existing WAS whose install path includes non ISO-8859-1 characters also might not work. For example, Chinese characters in the installation path are not supported.

 

Some portlets failed to deploy

If you encounter installation error EJPI0021W Some portlets failed to deploy, you might be able to recover the installation. This error can be caused by some portlets being left on WAS, or caused by WebSphere Portal not running. The user must first verify that WebSphere Portal starts and that the user can log in as the WebSphere Portal administrator. If this cannot be verified, something more severe than portlet deployment has gone wrong and manually installing portlets will not work. If WebSphere Portal login succeeds, you might be able to manually install portlets. To manually install portlets, run the following commands:

To drop all portlets, issue the following command: 

wp_root/bin/xmlaccess -in <wp_root>/package/removeallportlets.xml 
                      -user <portal_admin_id> 
                      -pwd <portal_admin_password> 
                      -url localhost:<port_number>/wps/config

 

Troubleshoot WAS

Warning when running configuration tasks to enable security

You might receive a warning message stating that it is not possible to modify credential-segment resources when running either of the following configuration tasks:

Ignore the warning message.

This can happen if you perform these steps:

  1. Install WebSphere Portal and WAS.

  2. Enable security, for example, by running the enable-security-cur configuration task.

  3. Uninstall WebSphere Portal and do not uninstall WAS.

  4. Install WebSphere Portal again.

  5. Enable security again, by running the enable-security-cur configuration task.
    After running this task you might see a message stating that it is not possible to modify credential-segment resources.

 

Troubleshoot failed attempts to access the portal

 

Portal URL does not open

If you try to open the portal URL, but the browser returns a 404 message (file not found), check the base URI and default home page. The portal does not work unless a base URI is configured. The default base URI is /wps. For example, if the default base URI and the default home page were configured for the portal, you would open the URL http://<hostname.yourco.com>:<port_number>/wps/portal, where hostname is the host name for the Web server that the portal uses and port_number is the transport port created by WAS.

 

Unable to connect to portal

WebSphere Portal is an application server that is running on WAS. If you are having trouble launching WebSphere Portal you might want to verify that the application server was successfully installed. To verify the application server, start the WAS Administrative Console and look for settings that are specific to WebSphere Portal. For example, WebSphere Portal installs the following entries in the left panel of the Administrative Console:

 

Login failed message displays and login attempt is unsuccessful after the correct user ID and password are entered

Perform the following procedures if you see the following message on the login page: Login failed. Specify a valid user ID and password.

 

Login attempt is unsuccessful, but no error message is displayed

If the login to the portal is unsuccessful, usually obvious error messages will be displayed. Typically, the error is the result of incorrectly entering a valid user ID and password, or, depending on the WebSphere Portal version and Fix Pack level, an error screen requesting that the user explicitly log out of portal at the end of a session.

In the case where login is not successful but no obvious error message is displayed, there are several possibilities, depending on the exact symptoms and system configuration.

If an authentication front end, such as Tivoli Access Manager is deployed and a corresponding Trust Association Interceptor is configured for WAS, there might be an error in the configuration of the authentication front-end component. Descriptions of how to debug that environment are beyond the scope of this documentation; consult the appropriate product specific documentation in this case.

If the authentication proxy and TAI are working correctly, there might be a problem in the WebSphere Portal JAAS login processing. Activating the PortalCoreTraceLogger will generate trace output from most of the JAAS loginmodules supplied with WebSphere Portal. The PDLoginModule, if present, can be traced by adding debug=true as a parameter to the loginmodule in portallogin.config.

If no authentication proxy or TAI are configured, and the symptom seen is that the user is immediately placed back at the login form after submitting the filled-in login form, a likely cause is that WAS single signon and the associated necessary cookie enablement is not correctly configured. Verify that your Web browser is enabled for cookies. A cookie with a valid LTPA token is needed to access URLs that are secured by WAS. If the browser is not configured to accept cookies, activate this feature. A good test is to activate cookie prompting in the browser; the methods to do this vary from browser to browser and are beyond the scope of this document. An "LTPAToken" cookie should be seen after the login form is submitted, and the DNS domain associated with that cookie must be correctly set to enable it to be sent back to WebSphere Portal on subsequent requests. If the DNS domain of the cookie is not correct, go to the WAS Administrative Console Security Center, and on the Authentication Tab, make the necessary corrections. Also, note that the single signon cookie domain must consist of at least two names separated by a period. For example, yourco.com is acceptable, but yourco or just .com is not.

 

Application Error message displays when accessing the portal

Verify that the WAS is installed correctly.

 

Redirected back to login screen

A problem that sometimes occurs as you attempt to install WebSphere Portal is that you might be able to activate WebSphere Portal but might not be able to log in. Specifically, after you submit your user name and password in response to the login screen, you are immediately redirected back to the login screen again.

Usually, this is a result of a configuration problem with the security support of WAS. An easy way to diagnose this problem is to activate cookie prompting. To resolve this problem, perform the following steps:

  1. In Internet Explorer, select Tools > Internet Options.

  2. Select the Security tab.

  3. Select the Web content zone that your browser uses to connect to WebSphere Portal. Usually, this will be the Internet zone.

  4. Select Custom Level. Scroll down until you see Cookies.

  5. Select Prompt for both stored and per-session cookies.

  6. Save and exit.

Internet Explorer should then prompt you whenever a server attempts to set a cookie on your browser. The prompt will say Security Alert and will ask if you will allow the Web site to place a cookie on your computer. Select the More Info button on the prompt to display the cookie name and other information.

When you attempt to log in to WebSphere Portal, see the following two cookies being set on your browser: JSESSIONID and LTPAToken. You might also see a third cookie, WasReqURL, if you access /wps/myportal directly and were redirected by WAS to the WebSphere Portal login screen.

If you don't see the LTPAToken cookie, then you will not be able to successfully log in to WAS and WebSphere Portal.

If this is the case, it is possible that the problem is that the domain of the LTPAToken cookie is not configured correctly in WAS. To correct this, perform the following steps:

  1. In the WAS Administrative Console, select Security Then click Authentication Mechanisms Then click LTPA.

  2. Select Single Signon in Additional Properties.

  3. Verify that Single Signon is enabled by checking the box, except in very rare instances when using Tivoli Access Manager WebSEAL as an authentication proxy in front of WAS and WebSphere Portal.

  4. Also, the Domain must be set such that a cookie marked with that domain will be sent to the browser and then returned on subsequent requests from the browser to WAS.

 

Cannot log in to WebSphere Portal environment with Active Directory as LDAP

When trying to log in to WebSphere Portal environment with Active Directory as LDAP over SSL, you might receive the following error:

The system could not log into your account.
Reason: The system could not retrieve your user account information data store. Please try again later.

To solve this problem, stop and start WebSphere Portal.

 

Problem: WASAdmin task fails to communicate with WAS Deployment Manager

The WASAdmin task might fail as a result of how you have your enviroment configured. For example, this problem can happen if you have Embedded Messaging installed on a WAS Deployment Manager system but the WAS node where Portal is installed does not have Embedded Messaging installed. In this case, Embedded Messaging is required on all WAS nodes in the cell, as it is used in inter-node communications.

Solution: Do not install Embedded Messaging on the WAS Deployment Manager system. However, if Embedded Messaging is already installed on the Deployment Manager system, also install Embedded Messaging on the WAS nodes where Portal is installed. To install Embedded Messaging, use the native WAS installation program to add to an existing copy of WAS and select to install the Embedded Messaging component.

 

Exceptions occur when starting WAS

There are some expected exceptions when setting up the Session persistence tables in WAS Version 5.0. The exceptions occur when starting a server with session persistence configured for the first time, or after dropping persisted session tables. The following exception is seen in the SystemOut.log file and can be ignored:

java.sql.SQLException: ORA-00955: name is already used by an existing object

 

Running addwpsinst.sh causes errors after remote installation

When running the addwpsinst.sh script to add WebSphere Portal to a WAS instance, you might see many errors such as this one:

[copy] Warning: package/filelist_wps.txt modified in the future.

These errors occur when the remote PC workstation used for WebSphere Portal installation is set to a different Greenwich mean time (GMT) than the iSeries system on which WebSphere Portal is installed. In such cases, an error message like the one cited above is displayed for each file being copied with the addwpsinst.sh script.

Solution: These errors do NOT indicate a problem with WebSphere Portal, and should simply be ignored.

 

iSeries login prompt freezes when installing remotely from Windows 2000

When installing WebSphere Portal remotely from a Windows 2000 workstation, the iSeries login prompt might freeze and not allow the user to enter anything in the fields.

Solution: Click on the Windows desktop, then click an input area in the login prompt. If the problem persists, cancel the installation and try again.

 

basic-config task fails when datbase schema has the same name as the database user

The basic-config configuration task might fail if you specify a database schema in the wpconfig.properties file with the same name as the database user.

Solution:

Edit...

/qibm/userdata/webas5/baseinstance/portalserver5/config/wpconfig.properties

Ensure that the DbUser and WpsDbSchema properties have different values. Try running the task again.

 

Parallel Portlet Rendering gets pipe timed out error

There is a timer value for the pipes reading the portlets content. Your iSeries might require a higher rendering time frame. "PEEX0110E: The underlying pipe timed out while reading" is logged and "This portlet is temporarily disabled" is shown on the Portal page.

Solution: Run wpsconfig.sh action-update-portletcontainersevice -DparallelRenderingTimeOut=xxxxx, from a Qshell prompt, where parallelRenderingTimeOut is the property that specifies the timeout value in milliseconds, and xxxxx is the new value. The default is 4000ms. The parallelRenderingTimeOut property is not specified in the wpconfig.properties file and must be specified on the command line to change the value.

 

addNode fails with timeout exception

On some machine configurations, WebSphere Portal components can cause a timeout exception when a node is being added to the Network Deployment in a cluster environment.

Solution: The problem can be avoided by increasing the Network Deployment's ConnectionIOTimeOut value before running the addNode command. However, if addNode has already been run, remove the node and uninstall the applications associated with that node from the Network Deployment instance using the Network Deployment administration console. For instructions on removing a node, refer to the Remove nodes from a Network Deployment instance topic of the iSeries Information Center.

Once you have removed the node, add a new node by following the instructions in the Install WebSphere Portal into a cluster topic, making sure to follow the directions for increasing the Network Deployment's ConnectionIOTimeOut value.

 

Installation program does not start

The WebSphere Portal installation program might not start if host servers are not running on the iSeries system.

Solution: Start host servers by entering the following on an OS/400 command line: 

STRHOSTSVR SERVER(*SIGNON *RMTCMD)

After host servers have been started, try running the WebSphere Portal installation program again.

 

Deployment into a cluster fails with FTP errors

Deployment of WebSphere Portal into a cluster might fail with a variety of FTP errors due to a problematic entry in the resources.xml file.

Solution: Edit...

/QIBM/UserData/WebAS5/instance/config/cells/cell/nodes/node/servers/server/resources.xml

Where instance is the Network Deployment instance, cellname is the cell name, nodename is the node name, and servername is the application server name. Comment out the Samples URL Provider entry (last entry in the file). Save the file and attempt deployment again.

See also