Troubleshooting migration

You might encounter problems while migrating from an older version of WebSphere® Application Server.

• While you are using the Version 8.5 Migration wizard to create a profile before migrating a configuration, you might see the following profile-creation error messages.

  profileName: profileName cannot be empty
  profilePath: Insufficient disk space

  These error messages might be displayed if you enter a profile name that contains an invalid character such as a space. Rerun the Migration wizard, and verify that there are no invalid characters in the profile name such as a space, quotes, or any other special characters.

• If you encounter a problem when you are migrating from a previous version of WebSphere Application Server to Version 8.5, check your log files and other available information.
  1. Look for the log files, and browse them for clues.
     • migration_backup_dir/logs/WASPreUpgrade.time_stamp.log
     • migration_backup_dir/logs/WASPostUpgrade.time_stamp.log
     • app_server_root/logs/clientupgrade.time_stamp.log
  2. Look for MIGR0259I: The migration has successfully completed or MIGR0271W: The migration completed with warnings in one of the log files.
     • migration_backup_dir/logs/WASPreUpgrade.time_stamp.log
     • migration_backup_dir/logs/WASPostUpgrade.time_stamp.log
     • app_server_root/logs/clientupgrade.time_stamp.log

     If MIGR0286E: The migration failed to complete is displayed, attempt to correct any problems based on the error messages that appear in the log file. After correcting any errors, rerun the command from the bin directory of the product installation root.

  3. Open the service log of the server that is hosting the resource that you are trying to access, and browse error and warning messages.
  4. With WebSphere Application Server running, run the dumpNameSpace command and pipe, redirect, or more the output so that it can be easily viewed.

     This command results in a display of all objects in WebSphere Application Server's namespace, including the directory path and object name.

  5. If the object that a client needs to access does not appear, use the administrative console to verify the following conditions.
     • The server hosting the target resource is started.
     • The web module or enterprise Java™ bean container hosting the target resource is running.
     • The JNDI name of the target resource is properly specified.
  6. Analyze the trace data from the migration tools or forward the data to the appropriate organization for analysis.
     When you use the WASPreUpgrade command or the WASPostUpgrade command, you can specify the following parameters for tracing:

     -traceString

     This is an optional parameter. The value trace_spec specifies the trace information that you want to collect.

     • Specify "*=all=enabled" (with quotation marks) to gather all possible trace information.

       This produces a very large trace file; for example, it can exceed 1 GB for the WASPostUpgrade command.

     • Specify "Migration.*=all" to gather only the migration information
     • Specify "Migration.Flow=all:Migration.*=finer" to gather most of the migration information.
     • Specify "Migration.Flow=finer:Migration.*=fine" to gather the minimum amount of migration data needed by support teams.

       This is the default.

     -traceFile

     This is an optional parameter. The value file_name specifies the name of the output file for trace information.

     If you do not specify the -traceString or -traceFile parameters, the command creates a trace file by default and places it in the backup_directory/logs directory.

  For current information available from IBM® Support on known problems and their resolution, read the IBM Support page. IBM Support also has documents that can save you time gathering information needed to resolve this problem. Before opening a PMR, read the IBM Support page.

• During the migration process, problems might occur while you are using the WASPreUpgrade tool or the WASPostUpgrade tool.
  • Problems can occur when you are using the WASPreUpgrade tool.
    • A Not found or No such file or directory message is returned.

      This problem can occur if you are trying to run the WASPreUpgrade tool from a directory other than the Version 8.5 app_server_root\bin. Verify that the WASPreUpgrade script resides in the Version 8.5 app_server_root\bin directory, and launch the file from that location.

    • The DB2® JDBC driver and DB2 JDBC driver (XA) cannot be found in the drop-down list of supported JDBC providers in the administrative console.

      The administrative console no longer displays deprecated JDBC provider names. The new JDBC provider names used in the administrative console are more descriptive and less confusing. The new providers will differ only by name from the deprecated ones.

      The deprecated names will continue to exist in the jdbc-resource-provider-templates.xml file for migration reasons (for existing JACL scripts for example); however, you are encouraged to use the new JDBC provider names in your JACL scripts.

    • You receive the following message:

      MIGR0108E: The specified WebSphere directory does not contain a WebSphere version that can be upgraded.

      The following possible reasons for this error exist:

      • If WebSphere Application Server Version 6.1 or later is installed, you might not have run the WASPreUpgrade tool from the bin directory of the Version 8.5 installation root.
        1. Look for something like the following message to display when the WASPreUpgrade tool runs: IBM WebSphere Application Server, Release 6.x.

           This message indicates that you are running the WebSphere Application Server Version 6.1 or later migration utility, not the Version 8.5 migration utility.

        2. Alter your environment path or change the current directory so that you can launch the Version 8.5 WASPreUpgrade tool.
      • An invalid directory might have been specified when launching the WASPreUpgrade tool.
    • The WASPreUpgrade tool might exit without backing up your previous environment.
      The tool might appear to run successfully as in the following example:

      MIGR0201I: The migration function initialized log file WASPreUpgrade.log. 
      MIGR0300I: The migration function is starting to save the existing Application Server environment.
      MIGR0302I: The existing files are being saved.
      MIGR0303I: The existing Application Server environment is saved.
      MIGR0420I: The first step of migration completed successfully.

      You might also see a message similar to the following example in the migration trace file:

      [10/9/08 18:26:40:363 CDT] 00000000 Save     1  
      Skipped instance dmgr01 because user root /opt/migration_backup/profiles/dmgr01 does not exist.

      The WASPreUpgrade tool writes out a copy of a profileList.ser file that contains pointers to the backup directory to be used by the WASPostUpgrade tool. If that file is not subsequently deleted by migration for any reason, the old paths are used instead of the real paths when you run the WASPreUpgrade tool in later migrations. To resolve this issue, you can safely delete the profileList.ser file and rerun the WASPreUpgrade tool.

    For more information, read WASPreUpgrade command.

    Avoid trouble: When migrating a Version 6.1 federated node to Version 8.5, the WASPreUpgrade command might fail. You might receive an error similar to the following example:

    [07/16/2011 11:07:10:357 CDT] MIGR0344I: Processing configuration file 
    /opt/WAS61fep/profiles/v6109node74_01/config/cells/ndcell/clusters/Station1EJBCluster
    /resources.xml.
    [07/16/2011 11:07:10:436 CDT] org.eclipse.emf.ecore.resource.Resource$IOWrappedExcept
    ion: Unresolved reference 'DataSource_1310769433958'. 
    (file:/opt/WAS61fep/profiles/v6109node74_01/config/cells/ndcell/clusters/Station1EJBC
    luster/resources.xml, 9, 323)
    java.lang.Exception: org.eclipse.emf.ecore.resource.Resource$IOWrappedException: 
    Unresolved reference 'DataSource_1310769433958'. 
    (file:/opt/WAS61fep/profiles/v6109node74_01/config/cells/ndcell/clusters/Station1EJBC
    luster/resources.xml, 9, 323)
    at com.ibm.wsspi.migration.document.wccm.WCCMDocument.setInputStream(WCCMDocument.ja
    va:162)

    You might encounter this problem on a WebSphere Version 6.1 node when a DB2 database using IBM JCC Provider Driver has been created, and the WebSphere Version 6.1 node is synchronized to the Version 8.5 deployment manager. The Version 6.1 node does not support the Version 7.0 or later driver level. The node synchronization process is failing to remove all of the driver definitions.

    To resolve this problem, backup any resources.xml files that are to be modified. Stop the Version 6.1 node agent process. Edit the WebSphere Version 6.1 node resources.xml files and remove the orphaned resources.jdbc:CMPConnectorFactory entries prior to running the WASPreUpgrade command. Do not edit the deployment manager copy.

  • Problems can occur when you are using the WASPostUpgrade tool.
    • A Not found or No such file or directory message is returned.

      This problem can occur if you are trying to run the WASPostUpgrade tool from a directory other than the Version 8.5 app_server_root\bin. Verify that the WASPostUpgrade script resides in the Version 8.5 app_server_root\bin directory, and launch the file from that location.

    • You receive the following message:

      MIGR0102E: Invalid Command Line. MIGR0105E: You must specify the primary node name.

      The most likely cause of this error is that WebSphere Application Server Version 6.1 or later is installed and the WASPostUpgrade tool was not run from the bin directory of the Version 8.5 installation root.

      To correct this problem, run the WASPostUpgrade command from the bin directory of theVersion 8.5installation root.

    • You receive the Unable to copy document to temp file error message. Here is an example:

      MIGR0304I: The previous WebSphere environment is being restored.
      com.ibm.websphere.management.exception.DocumentIOException: Unable to copy document to temp file: 
        cells/sunblade1Network/applications/LARGEApp.ear/LARGEApp.ear

      Your file system might be full. If your file system is full, clear some space and rerun the WASPostUpgrade command.

    • You receive the following message:

      MIGR0108E: The specified WebSphere directory does not contain WebSphere version that can be upgraded.

      The following possible reasons for this error exist:

      • If WebSphere Application Server Version 6.1 is installed, you might not have run the WASPostUpgrade tool from the bin directory of the Version 8.5 installation root.
        1. Look for something like the following message to display when the WASPostUpgrade tool runs: IBM WebSphere Application Server, Release 6.1.

           This message indicates that you are running a migration utility from a previous release, not the Version 8.5 migration utility.

        2. Alter your environment path or change the current directory so that you can launch the Version 8.5 WASPostUpgrade tool.
      • An invalid directory might have been specified when launching the WASPreUpgrade tool or the WASPostUpgrade.
      • The WASPreUpgrade tool was not run.
    • You receive the following error message:

      MIGR0253E: The backup directory migration_backup_directory does not exist.

      The following possible reasons for this error exist:

      • The WASPreUpgrade tool was not run before the WASPostUpgrade tool.
        1. Check to see if the backup directory specified in the error message exists.
        2. If not, run the WASPreUpgrade tool.

           Read WASPreUpgrade command for more information.

        3. Retry the WASPostUpgrade tool.
      • An invalid backup directory might be specified.

        For example, the directory might have been a subdirectory of the Version 6.1 or later tree that was deleted after the WASPreUpgrade tool was run and the older version of the product was uninstalled but before the WASPostUpgrade tool was run.

        1. Determine whether or not the full directory structure specified in the error message exists.
        2. If possible, rerun the WASPreUpgrade tool, specifying the correct full migration backup directory.
        3. If the backup directory does not exist and the older version it came from is gone, rebuild the older version from a backup repository or XML configuration file.
        4. Rerun the WASPreUpgrade tool.
    • Version 8.5 applications fail to install.

      Manually install the applications using the wsadmin command after WASPostUpgrade has completed.

      To manually install an application that failed to install during migration, use the wsadmin command to run the install_application_name.jacl script that the migration tools created in the backup directory.

      In a Linux® environment, for example, use the following parameters:

      ./wsadmin.sh -f migration_backup_directory/install_application_name.jacl -conntype NONE

    Read WASPostUpgrade command for more information.

  • The trace file exceeds its 400 megabytes allocation, but WASPostUpgrade is still running. If additional disk space is not available, the migration will fail.
    If you think you might encounter this problem during your migration, complete the following actions:

    1. Stop the Migration wizard before the WASPostUpgrade command is issued.
    2. Run the WASPostUpgrade command from the command line for each profile you are migrating.

       When you run the WASPostUpgrade command from the command line:

       • Include the -oldProfile and -profileName parameters to indicate the profile you want to migrate.
       • Add the com.ibm.ejs.ras.TraceNLS* parameter to the trace string to reduce the size of your trace log. For example you might want to specify the following trace setting:

         com.ibm.ejs.ras.TraceNLS*=info

• When you use the Migration wizard to migrate a profile from WebSphere Application Server Version 6.0.2 to Version 8.5 on a Solaris x64 processor-based system, the migration might fail during the WASPostUpgrade step.
  You might see messages similar to the following in migration_backup_dir/logs/WASPostUpgrade.time_stamp.log:

  MIGR0327E: A failure occurred with stopNode.
  MIGR0272E: The migration function cannot complete the command.

  WebSphere Application Server Version 6.0.2 uses a Java Virtual Machine (JVM) in 32-bit mode. The Migration wizard for Version 8.5 calls the WASPostUpgrade.sh script, which attempts to run the JVM for Version 6.0.2 in the 64-bit mode when the server stops the Version 6.0.2 node.

  Complete the following actions to remove the incomplete profile and enable WebSphere Application Server to correctly migrate the Version 6.0.2 profile:

  1. From a command line, change to the app_server_root/bin directory.
     For example, type the following command:

     cd /opt/IBM/WebSphere/AppServer/bin

  2. Locate the WASPostUpgrade.sh script in the app_server_root/bin directory, and make a backup copy.
  3. Open the WASPostUpgrade.sh script in an editor, and perform the following actions:
     1. Locate the following line of code:

        . "$binDir" /setupCmdLine.sh

     2. Insert the following line of code after the code that was identified in the previous step:

        JVM_EXTRA_CMD_ARGS=""

     3. Save the changes.
  4. Use the following command to delete the incomplete Version 8.5 profile that was created during the migration process:

     app_server_root/bin/manageprofiles.sh -delete -profileName profile_name 

  5. Delete the profile_root directory of the Version 8.5 profile that was removed in the previous step.
  6. Rerun the Migration wizard.
• If you select the option for the migration process to install the enterprise applications that exist in the Version 6.1 or later configuration into the new Version 8.5 configuration, you might encounter some error messages during the application-installation phase of migration.

  The applications that exist in the Version 6.1 or later configuration might have incorrect deployment information—typically, invalid XML documents that were not validated sufficiently in previous WebSphere Application Server runtimes. The runtime now has an improved application-installation validation process and will fail to install these malformed EAR files. This results in a failure during the application-installation phase of WASPostUpgrade and produces an E error message. This is considered a fatal migration error.

  If migration fails in this way during application installation, you can do one of the following:

  • Fix the problems in the Version 6.1 or later applications, and then remigrate.
  • Proceed with the migration and ignore these errors.

    In this case, the migration process does not install the failing applications but does complete all of the other migration steps.

    Later, you can fix the problems in the applications and then manually install them in the new Version 8.5 configuration using the administrative console or an install script.

• Because of the inclusion of the javax.ejb.Remote annotation in the EJB 3.0 specification, certain EJB 2.1 beans might fail to compile if Enterprise Java Beans are written to import the entire javax.ejb and java.rmi packages.
  Compilation errors similar to those in the following example might occur:

  ejbModule/com/ibm/websphere/samples/trade/ejb/QuoteHome.java(17): The type Remote is ambiguous