IBM Support

Collect troubleshooting data for installation or upgrade problems with WebSphere Process Server (WPS)

Technote (troubleshooting)


You are having an installation or upgrade problem with IBM WebSphere Process Server. You would like to know what documentation you must collect (MustGather) so that the WebSphere Process Server Support team can diagnose your problem. If you gather this documentation before contacting support it will expedite the troubleshooting process, and save you time.

Resolving the problem

Collect this MustGather data before contacting IBM Support:

Collecting general information for all problems
Provide a complete description of the problem, including the following information:

  • Was software or hardware maintenance applied?

  • Which WebSphere Process Server version, release, and maintenance level are you using?

  • Which operating system version, release, and maintenance level are you using?

  • If applicable, which related products, version, and release levels are you using?

Collecting data for installation and upgrade problems

Required (MustGather) data:

  • When did the problem first occur? Include the details of the steps that you followed and the commands that you ran that lead to the problem. If the problem involves an upgrade, include the previous and new version information.

  • Is the problem a one time failure or reoccurring?

  • Did the failure occur while doing a specific task?

  • If you are using the product on the z/OS operating system, is the failure occurring in more than one address space?

  • If you are able to start the installer and you partially completed the WebSphere process server installation, compress the following files into an archive and send them to IBM Support.

    • For WebSphere Process Server Versions 6.1.x and 6.2.x, collect all of the files in the following directories:
      • install_root/logs

      • user_home/waslogs

      • /tmp/niflogs
    • For WebSphere Process Server Version 7.0.x, collect all of the files in the following directories:
      • install_root/logs

      • user_home/waslogs

      • IM_Data
        The IM_Data directory is the complete Installation Manager Data Agent directory. For more information, see the Installation Manager data default location.

        Note: Depending on the operating system and archiving method, the hidden directory ( IM_data/.settings) might not get included. Make sure the IM_Data/.settings directory is included with the archive. The file under ".settings" contains the Installation Manager default and repositories settings.

      Visit the WebSphere Process Server V7 information center to see the complete list of default install_root locations.

Optional (MustGather) data:
  • If you have WebSphere Application Server installed, run the versionInfo command and provide the output. The versionInfo command indicates which version of WebSphere Application Server is installed. It also indicates whether you have feature packs installed. To capture the versionInfo output, open a terminal session or command prompt. Navigate to the WAS_HOME/bin subdirectory, where WAS_HOME represents the installation directory of WebSphere Application Server. Run the following command, depending on your operating system:

    • Windows
      versionInfo.bat -maintenanacePackages >versioninfo.txt

    • AIX, HP-UX, Linux, Solaris
      ./ -maintenanacePackages >versioninfo.txt
    The command produces a file named versioninfo.txt, which you need to send to IBM Support.

Troubleshooting hints and tips

Diagnostic tips:

Exchanging data with IBM Support

  1. See Exchanging information with IBM Technical Support for FTP and email instructions using the IBM Enhanced Customer Data Repository (ECuRep).

  2. Go to the Service Request page to open or update a problem. If you have a SoftwareXcel enterprise edition for zSeries contract, you can also ask non-defect installation and usage questions.

    Note: Always update your Service Request (problem record) to indicate that data has been sent.

If you need to speak to an IBM technical support representative, call your country representative. If you need to speak to an IBM technical support representative in the US, call 1-800-IBM-SERV.

Additional information

Enabling the Installation Manager trace

Warning: If you enable the Installation Manger trace, it can consume a large amount of hard drive space and it is likely to cause Installation Manager to crash. This scenario likely results in irreversible corruption in the Data agent directory. Do not enable the Installation Manager trace unless requested by the IBM Support team. Make sure that you backup the Installation Manager Data agent directory and verify that you have adequate hard drive space for Data Agent directory.

  1. Navigate to the IM_DATA/logs directory, and create a file named

  2. Copy the following data into the file:

    If Installation Manager is already running, you must restart it for tracing to take effect.

Locating the Installation Manager Data directory

The Installation Data Directory contains logs and the repository that tracks installed products. The exact location of this data depends on whether you have installed Installation Manager as a root user (administrative user), or as a non-root user (non-administrative user). If you are in doubt, check both locations as indicated in the following table.

The following table indicates the default directory that contains the Installation Manager data.

Note: Some of these directories refer to the user's home directory.

Platform Installation Type Default Data Location
Windows 2003
Windows XP
administrator C:\Documents and Settings\All Users\
Application Data\IBM\
Installation Manager
Windows 2003
Windows XP
non-administrator C:\Documents and Settings\
<user_name>\Application Data\
IBM\Installation Manager
Windows Vista
Windows 7
Windows 2008
administrator C:\ProgramData\IBM\
Installation Manager
Windows Vista
Windows 7
Windows 2008
non-administrator C:\Users\<user_name>\
Installation Manager
root /var/ibm/InstallationManager
non-root user_home/var/ibm/

Locating the .nifregistry file

The .nifregistry file helps WebSphere utilities locate the WebSphere Application Server V6.1 and V7.0 installations present on a system. The file is located outside the directory to which the product is installed and the location can vary depending on whether the product was installed as a root user or a non-root user.

If the product is being installed as the root user (or an administrative user on Windows), then the .nifregistry file is in a specific location, as listed below:

  • AIX:

  • HP-UX, Linux, and Solaris:

  • Windows:
    In the main Windows directory, typically: C:\Windows\.nifregistry

If the product is being installed as a non-root user (or a user without administrative authority on Windows), then the location of the .nifregistry file depends on the home directory for the user. For a non-root user installation, look for a subdirectory named .nif under the home directory for the user. The .nifregistry file is located in that directory.

Locating the current user's home directory

If the installation fails to start up, log files for V6.1 and V7.0 might be written to a directory called waslogs under the system temp directory. Also, when the product is installed as a non-root user, the .nifregistry file can be placed in a subdirectory in the home directory for the user. Here are some hints for locating the home directory for the user:

  • For AIX, Linux, HP-UX, and Solaris:
    The home directory for the user usually can be accessed by changing to a directory named " ~ " (tilde character) on those operating systems. For example, cd ~

  • For Windows:
    For Windows 2003 and Windows XP, the home directory for the user is typically the following directory:
    C:\Documents and Settings\

    For Windows Vista, Windows 7, and Windows 2008, the home directory for the user is typically the following directory:
Hint: You can sometimes directly access the home directory for the current user by entering %userroot% into a File Explorer address bar.

Collecting logs if WebSphere Application Server / WebSphere Process Server 6.x installer is unable to start

If the installer is not able to start up and log files do not exist, then it is necessary to invoke a trace to provide more diagnostic data. Invoke the installer at the command-line, adding the following parameters:
  • Windows
    -is:log c:\bootstrap.log.txt -is:javaconsole >c:\install.log.txt

    install.exe -is:log c:\bootstrap.log.txt -is:javaconsole >c:\install.log.txt

  • AIX, HP-UX, Linux, and Solaris
    -is:log /tmp/bootstrap.log -is:javaconsole >/tmp/install.log.txt

    ./install -is:log /tmp/bootstrap.log -is:javaconsole >/tmp/install.log.txt

Note: The >c:\install.log.txt or >/tmp/install.log.txt must be the last parameter in the command. Be sure you have write permission to that directory. Check the logs that are produced and you should be able to see the root cause of installer not being able to start.

Related information

Troubleshooting Guide For WebSphere Process Server
Recommended fixes
WPS installation and database configuration Documents

Document information

More support for: WebSphere Process Server
Installation & Configuration

Software version: 6.1, 6.1.2, 6.2, 7.0

Operating system(s): AIX, HP-UX, Linux, Solaris, Windows, z/OS

Reference #: 1267921

Modified date: 17 March 2011