Troubleshoot WebSphere Portal installation

This section contains information that can assist you in preventing, identifying, and correcting problems related to WebSphere Portal. For information related to specific components, see the appropriate troubleshooting topic.

 

Problem: General steps to perform if the installation fails

Solution: If the WebSphere Portal installation fails, follow these steps:

  1. If the WebSphere Portal installation fails, check the WebSphere Portal logs.

  2. Verify that WebSphere Application Server (WAS) has been installed correctly. If you did not use WebSphere Portal installation program to install WAS, ensure that the correct WAS Fix Packs and interim fixes are installed.

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

  4. Change the time-out request for the SOAP client. The default, in seconds, is 180. Edit...

    was_home/properties/soap.client.props

    Change the line to: 

    com.ibm.SOAP.requestTimeout=6000

 

Problem: Reinstall after a failed installation

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

  1. If an uninstallation program is available, run it before reinstalling the product. If the installation failed before the uninstallation program was created or if the uninstallation program fails, manually delete the installation directory and all of its contents before reinstalling the product. uninstallation.

  2. 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.

 

Problem: 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.

Solution:

  1. Open the Administrative Console for WAS. Verify that all of the WebSphere Portal components were removed by the previous uninstallation. Manually remove any of the components that remain. This includes the following elements:

    Enterprise application: WebSphere Portal Enterprise Application
    Application server: WebSphere Portal
    Data sources: wpsdbDS and wmmDS
    JDBC driver: wpsdbJDBC

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

  3. Restart the installation.

 

Problem: Search Collections are not removed during an uninstall

Solution:

  1. Remove the Search Collections before uninstalling.

  2. Manually remove the Search Collections by deleting...

    was_home/searchcollectionname

    ...after an uninstall is complete.

 

Problem: Installation fails due to path problem

Installation can sometimes fail if you download installation files to a local hard drive or a network drive and use long directory paths for the directories corresponding to the product CDs.

Solution: Where possible, specify short path names that do not contain special characters.

 

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

Solution: Installing 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.

 

Problem: Console mode installation not available for bidirectional languages

When installing WebSphere Portal in console mode on machines with bidirectional language support, an error is generated, and the installation exits.

Solution: Console mode installation is not supported for bidirectional languages, such as Hebrew and Arabic. When installing WebSphere Portal in a bidirectional language, you cannot use console mode. Instead, perform the installation using the graphical interface or using a response file.

 

Problem: Installation fails due to insufficient disk space

Solution: If you receive a message during installation informing you that there is insufficient disk space to install WebSphere Portal, you can complete one of the following steps:

  • Select a different disk drive or partition on which to perform the installation.

  • Exit the installation program, free up disk space on the partition to which you are attempting to install, and start the installation program again.

  • Solaris: Check that the/var/tmp directory contains 250KB or more free space.

 

Installation fails with the message "Please make sure you have at least 100MB free space in %TEMP% directory."

This message may be displayed even if your %TEMP% directory has more than 100MB of free space. If you have more than 100MB of free space, it is likely the install.bat (or install.sh) had problems copying some files to your %TEMP% directory.

There are several reasons this might happen:

  • You are installing from a network drive, and lost the connection in the middle of the installation.

  • You copied the cd images to your local machine but the permissions of the files in cdSetup are preventing the files from being copied.

  • Your %TEMP% directory contains some files used by the previous WebSphere Portal installation.

Solutions:

  • Copy the install image to a local harddisk drive, set the correct file permissions, and run install.bat (or install.sh) from the local hard disk.

  • Remove files in the %TEMP% directory and rerun install.bat (or install.sh).

 

Problem: Desktop display width doubles when running installation program

When running the WebSphere Portal installation program on a machine with the Windows 2000 operating system, you might encounter an error that causes the desktop to be displayed at twice its normal width, so that only half of the desktop can be viewed. This problem is due to an issue with Java 1.4 and the display settings of the monitor. This problem can occur for any of the ISMP-based wizards, such as the configuration wizard.

Solution 1: Reduce the refresh rate for the monitor.

  1. Exit the installation program (if still running).

  2. Click Start > Settings > Control Panel.

  3. Double-click Display.

  4. In the Display Properties window, click Settings > Advanced > Monitor.

  5. Change the refresh rate to a lower value. For example, if the refresh rate is set to 85 Hertz, you can change it to 60 Hertz.

  6. Click OK > OK >Yes to save your changes.

After you complete the WebSphere Portal installation, restore your display settings to their previous values.

Solution 2: Decrease screen resolution

(This solution increases the pixel size on your screen to increase the size of the image.)

  1. Exit the installation program (if still running).
  2. Click Start > Settings > Control Panel.
  3. Double-click Display.
  4. Click Settings.
  5. In the Screen Area section, move the slider to the left (toward "Less"). If your monitor resolution is at its lowest setting, refer to Solution 1 above.
  6. Click OK > OK > Yes to save your changes.

After you complete the WebSphere Portal installation, restore your display settings to their previous configuration.

 

Problem: 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.

Solution: 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:

  1. Change directory to the WebSphere Portal configuration directory:

      cd <wp_root>/config.

  2. 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

  3. To install all portlets, issue the appropriate command for your operating system:

    • UNIX: ./WPSconfig.sh portlets -DPortalAdminPwd=password

    • Windows: WPSconfig.bat portlets -DPortalAdminPwd=password

 

Problem: Translation Server fails after adding wts.jar to classpath

Translation Server fails if the incorrect wts.jar file is added to the classpath.

Solution: Only the wts.jar file in the Translation Server install directory should be added to the classpath. If you have added one of the wts.jar files in the wp_root directory, remove it from the classpath and add the correct jar file to the classpath.

 

Problem: Errors occur during installation indicating that WAS is already running

During the installation of WebSphere Portal, the installation program attempts to start WAS. If WAS is already running, the following error messages are logged in the startServer.log file: 

   ADMU3028I: Conflict detected on port 8880.  Likely causes: 
     a) An instance of the server server1 is already running  
     b) some other process is using port 8880
   ADMU3027E: An instance of the server may already be running: server1
   ADMU3002E: Exception attempting to process server server1

Solution: These errors do not affect the WebSphere Portal installation and can be ignored.

 

Problem: Administrative Console not loading

WebSphere Portal installs the WAS Administrative Console application into the WebSphere Portal appserver so that it can be used to administer the application server without requiring another application server instance (by default, server1) to be configured or operational. The default port used for communication is 9081.

On Windows, a Start Menu item is created to invoke the Administrative Console. If this menu item fails to load the console because of a HTTP 404 error that means that the Application Server is assigned a different administration port than was configured in the shortcut for this Start Menu item.

Solution: Change the property of WAS Administrative Console in Windows Start Menu (Start > Programs >IBM WebSphere > Application Server v5.1 > Administrative Console) as appropriate. For example,

C:\Program Files\Internet Explorer\IEXPLORE.EXE http://<hostname>:9090/admin/

to

C:\Program Files\Internet Explorer\IEXPLORE.EXE http://<hostname>:9081/admin/

 

Problem: WebSphere Portal configuration fails

If the configuration of WebSphere Portal fails with an error similar to the one below, it might be that there is not enough swap space. 

BUILD FAILED
file:../config/actions/was_cfg.xml:592: Execute failed: java.io.IOException: Not enough space

Total time: 44 minutes 10 seconds

Solution: Increase your swap space to a minimum of 2.5 GB. 3.0 GB is preferred.

 

Problem: Errors related to XADatasources prevent restarting WAS

If WAS is stopped improperly or unexpectedly, you might see errors similar to the one below when you try to restart: 

J2CA0061W: Error creating XA Connection and Resource com.ibm.ws.exception.WsException: 
DSRA8100E: Unable to get a XAConnection from the DataSource.

When this happens, you will be unable to restart WAS. This is because there are XA transactions still pending in the translog directory.

Solution: Delete the transaction logs in the $WAS_HOME tranlog/WebSphere_Portal directory, then restart WAS.

 

Problem: WpsHostPort property value not updated during installation

If the wpconfig.properties file is locked during installation, such as when it is open in a text editor, this can prevent the WpsHostPort property value from being updated properly to 9081. Although this is unlikely to occur during most installation scenarios, it could happen if you are installing on an existing WAS with security enabled, because this installation scenario requires you to perform the installation in a series of manual steps.

If the WpsHostPort property value is not set correctly, you will encounter problems if you perform a task that refers to the wpconfig.properties file for the WpsHostPort property, such using the xmlaccess command to deploy security credentials or portlets. Because the command will attempt to use the default value of 80 for WpsHostPort instead of 9081 (which is what the xmlaccess command expects), the command will fail.

Solution: Edit the wpconfig.properties file with a text editor, and change the value of the WpsHostPort property to 9081.

 

Related to Windows

 

Problem: WAS silent installation fails on Windows

On Windows, the silent installation fails if the user lacks permissions. In interactive mode, the install will catch the error and display a message. The GUI installer will not let the installation continue until the permissions are set either by the GUI installer or the System Administrator.

Solution: have the permissions set as stated in Preparing your Windows machine.

 

Problem: Installation program incorrectly identifies Windows 2003 operating system

When installing WebSphere Portal on Windows 2003, an error similar to the following error might be displayed in the installation log file: 

   EJPC1517I The Discovered specific Operating System type and version  
             Is winxp(5.0,2.0,0.0,0.0,0.0)

Solution: Due to how different levels of Java report Windows 2003, the installation program might identify the operating system incorrectly as either Windows 2000 or Windows XP. This error does not affect the WebSphere Portal installation and can be ignored.

 

Problem: WAS installation stalls on Windows 2003 when installing from a network drive

When installing WAS on a Windows 2003 machine, the installation can stall if you are attempting to perform the installation from a network file system.

Solution: Windows 2003 includes security policy settings that can prevent some programs from being run from a network file system without permission. In this case, the WAS installation program is being denied access and is unable to complete. To allow such programs to run, update your security settings, as described in the following steps:

  1. Update the list of trusted sites on the Windows 2003 machine by adding the network file system containing the program you want to run.

    1. Open the Control Panel.

    2. Double-click Internet Options, and select the Security tab.

    3. Click Trusted sites, and then click Sites.

    4. Enter the network share, and click Add. Note that URL syntax is required for this information. For example, if you are connecting to share myshare on machine myhost, you would enter file://myhost/myshare.

    5. Click OK.

  2. Change the security level for the Trusted sites zone.

    1. On the Trusted sites page, click Custom Level.

    2. Locate Launching applications and unsafe files in the list of settings, and click Enable.

    3. Click OK.

  3. Click OK to save the changes.

After completing these changes, be able to run the WAS installation program from a network file system.

 

Problem: Installation program displays a dialog for amqicsdn.exe file when installing on Windows 2003

When installing WebSphere Portal on a Windows 2003 machine from a network file system, the installation might display a dialog asking whether you want to open the amqicsdn.exe file.

Solution: Windows 2003 includes security policy settings that can prevent some programs from being run from a network file system without permission. In this case, the amqicsdn.exe file cannot run unless you perform one of the following steps:

  • Open the file during installation. If you are performing an interactive installation with the graphical installation program, click Open to allow the amqicsdn.exe file to run. The WebSphere Portal installation will continue.

  • Change your security settings. If you do not want to be prompted when the amqicsdn.exe file is run or if you intend to perform a silent installation, update your security settings, as described in the following steps:

    1. Update the list of trusted sites on the Windows 2003 machine by adding the network file system containing the program you want to run.

      1. Open the Control Panel.

      2. Double-click Internet Options, and select the Security tab.

      3. Click Trusted sites, and then click Sites.

      4. Enter the network share, and click Add. Note that URL syntax is required for this information. For example, if you are connecting to share myshare on machine myhost, you would enter file://myhost/myshare.

      5. Click OK.

    2. Change the security level for the Trusted sites zone.

      1. On the Trusted sites page, click Custom Level.

      2. Locate Launching applications and unsafe files in the list of settings, and click Enable.

      3. Click OK.

    3. Click OK to save the changes.

 

Problem: WebSphere MQ installation fails

If you are performing a manual installation of WebSphere Portal where you are installing the different components required by WebSphere Portal separately, you might encounter an error during the installation of WebSphere MQ or the application of service to WebSphere MQ because the amqxms0n.dll file is in use by the Windows Management Instrumentation system service.

Solution: To avoid this situation, ensure that the Windows Management Instrumentation system service is stopped before installing:

  1. Open the Control Panel, and double-click Administrative Tools.

  2. Click Services to display a list of system services.

  3. Right-click on Windows Management Instrumentation, and click Stop.

After the service is stopped, you can proceed with the installation.

 

Related to UNIX

 

Problem: Installation fails on UNIX because embedded messaging user and groups cannot be created

WebSphere Portal requires the embedded messaging feature of WAS. On UNIX platforms (AIX, Solaris, HP-UX, and all Linux), the embedded messaging feature requires the creation of the mqm system user and the mqm and mqbrkrs groups before installing WAS.

The WebSphere Portal installation attempts to create the user and groups, but if it is unable to do so, the installation program exits.

Solution: If the WebSphere Portal installation program cannot create the required user and groups, they must be created manually before installing WebSphere Portal. This procedure is documented in the WAS Information Center. Note that if you are using an LDAP directory to manage your user information, create the user and groups in the LDAP directory.

 

Problem: (Linux and UNIX only) Some DBCS fonts may be corrupted when installing from console or GUI interface

On some versions of Unix and Linux, certain double-byte character sets can be corrupted during installation. When installing from the console, Korean, Traditional Chinese, and Simplified Chinese character sets are affected. Using the GUI installation, Traditional Chinese and Simplified Chinese character sets are affected.

Solution:

  • When installing, use the locales listed below to prevent corruption of the DBCS character sets.

  • The Korean character set locale only needs to be changed for console installation.

  • To change the system locale, enter:

    • On HP-UX and Red Hat, for example export LANG=zh_CN.utf8

    • On SuSE, for example

      export LANG=zh_CN.utf8

      export LC_CTYPE=zh_CN.utf8

Linux or Unix using the console.">
Correct character sets for console installation.
Console Install Simplified Chinese   Traditional Chinese Korean
HP-UX 11v zh_CN.hp15CN zh_TW.big5 ko_KR.eucKR
SuSE SLES 8 zh_CN.gb18030 zh_TW ko_KR.euckr
  zh_CN.gbk    
  zh_CN    
Red Hat AS 3 Update 1 zh_CN.gb18030 zh_TW ko_KR.euckr
  zh_CN.gbk    
  zh_CN    

Linux or Unix using the console.">
Correct character sets for GUI installation.
GUI Install Simplified Chinese   Traditional Chinese
HP-UX 11v zh_CN.hp15CN zh_TW.big5
    zh_TW.eucTW
SuSE SLES 8 zh_CN.gb18030 zh_TW
  zh_CN.utf8  
Red Hat AS 3 Update 1 zh_CN.gb18030 zh_TW
  zh_CN.utf8 zh_TW.euctw
    zh_TW.utf8

 

Related to AIX

 

Problem: Portal JVM exits with an error message on AIX

When you use large Java heaps for applications under AIX, you have to set an environment parameter to a specific value. Otherwise portal JVM exits with an error message.

Cause: The cause for this message is that you tried to allocate a Java heap for the Portal application that is larger than 1GB.

Solution: On 32-bit AIX systems the JVM has eight 256MB memory segments that it can use. With large heaps it may happen that this total of 2GB is not sufficient, as the real process size is not only determined by the Java heap but also by the system heap. In this case portal JVM exits with the following message: 

Unable to map Java heap of requested size, perhaps the maxdata value is too large - see Java README.HTML for more information.
Unable to allocate an initial java heap of XXXXXXXXX bytes.
**Out of memory, aborting** 
*** panic: JVMST016: Cannot allocate memory for initial java heap

In order to be able to have heaps larger than 2 GB, change the memory allocation scheme that the JVM uses.

In your shell or the script that starts the portal enter the following line:

export LDR_CNTRL=MAXDATA=0x40000000

Where, the first digit after the x (in the example 4) determines the number of 256MB blocks available to the JVM. If the requested Java heap size is already larger, for example 1536MB, the JVM does no longer allocate the Java heap from those blocks but from free memory provided by the operating system.

Specify a suitable value for your system to avoid JVM startup problems caused by memory allocation requirements that are too high.

For more information on the JVM refer to IBM's JVM diagnostics guide at the following Web site: http://www.ibm.com/developerworks/java/jdk/diagnosis/

 

Related to Linux

 

Problem: WebSphere Portal installation message states that Suse SLES 9 is not supported

Solution:Suse SLES 9 is supported. Ignore this message and continue installation on Suse SLES 9.

 

Related to Solaris

 

Problem: WebSphere Portal installation fails with an I/O error when installing from CD-ROM made from CD ISO image file

On Solaris, installation may fail if the CD-ROM created from a downloaded ISO image contains nearly 700 MB of data.

Solution: On the machine where you are installing WAS, copy the ISO image file to the hard disk, mount the ISO image, and run the installation program from the mounted image.

 

Problem: Errors indicating missing libraries are generated during installation on Solaris 9

During installation on Solaris 9, errors similar to the following errors might be generated in the installmessages.txt file: 

      EJPCA1514W: Discovery processing did not locate the X11R6 libraries
      EJPCA1516W: Discovery processing did not locate all required libraries needed by the Productivity 
                  Components. If these libraries are not installed, the Productivity Components may not 
                  function properly.

Solution: These errors do not affect the WebSphere Portal installation and can be ignored.

 

See also

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.

 

AIX is a trademark of the IBM Corporation in the United States, other countries, or both.