Troubleshooting migration

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

Procedure

• If you encounter a problem when you are migrating from a previous version of WebSphere Application Server to V6.1, check your log files and other available information.

  1. Look for the log files, and browse them for clues.

     • migration_backup_dir/WASPreUpgrade.time_stamp.log

     • profile_root/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 the migration_backup_dir/WASPreUpgrade.time_stamp.log, profile_root/logs/WASPostUpgrade.time_stamp.log, or 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 Log and Trace Analyzer built into the Application Server Toolkit (AST) on the service log of the server that is hosting the resource that you are trying to access, and use it to browse error and warning messages.

     See Debugging components in the Application Server Toolkit .

  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 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 JavaBean container hosting the target resource is running.

     • The JNDI name of the target resource is properly specified.

  If none of these steps solves the problem, see if the problem is identified and documented using the links in Diagnosing and fixing problems: Resources for learning. If you do not see a problem that resembles yours or if the information provided does not solve your problem, contact IBM support for further assistance. See Troubleshooting help from IBM. For current information available from IBM Support on known problems and their resolution, see 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, see 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 WebSphere Application Server V6.1 app_server_root\bin. Verify that the WASPreUpgrade script resides in the V6.1 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 V5.x or 6.0.x is installed, you might not have run the WASPreUpgrade tool from the bin directory of the V6.1 installation root.

        1. Look for something like the following message to display when the WASPreUpgrade tool runs: IBM WebSphere Application Server, Release 5.0.

           This message indicates that you are running the WebSphere Application Server Version 5.0 migration utility, not the V6.1 migration utility.

        2. Alter your environment path or change the current directory so that you can launch the WebSphere Application Server V6.1 WASPreUpgrade tool.

      • An invalid directory might have been specified when launching the WASPreUpgrade tool.

    See WASPreUpgrade command.

  • Problems can occur when you are using the WASPostUpgrade tool.

    • A "Not found" or "No such file or directory" message is returnedl.

      This problem can occur if you are trying to run the WASPostUpgrade tool from a directory other than the WebSphere Application Server V6.1 app_server_root\bin. Verify that the WASPostUpgrade script resides in the V6.1 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 V5.x or 6.0.x is installed and the WASPostUpgrade tool was not run from the bin directory of the V6.1 installation root.

      To correct this problem, run the WASPostUpgrade command from the bin directory of the WebSphere Application Server V6.1 installation root.

    • When you migrate the federated nodes in a cell, you receive the following error messages:

      MIGR0304I: The previous WebSphere environment is being restored.
       com.ibm.websphere.management.exception.RepositoryException:
       com.ibm.websphere.management.exception.ConnectorException: ADMC0009E:
         The system failed to make the SOAP RPC call: invoke
      MIGR0286E: The migration failed to complete.

      A connection timeout occurs when the federated node tries to retrieve configuration updates from the deployment manager during the WASPostUpgrade migration step for the federated node. Copying the entire configuration might take more than the connection timeout if the configuration that you are migrating to V6.1 contains any of the following elements:

      • Many small applications

      • A few large applications

      • One very large application

      The best practice is to modify the timeout value before running the WASPostUpgrade command to migrate a federated node.

      1. Go to the following location in the V6.1 directory for the profile to which you are migrating your federated node:

         profile_root/properties 

      2. Open the soap.client.props file in that directory and find the value for the com.ibm.SOAP.requestTimeout property. This is the timeout value in seconds. The default value is 180 seconds.

      3. Change the value of com.ibm.SOAP.requestTimeout to make it large enough to migrate your configuration. For example, the following entry would give you a timeout value of a half of an hour:

         com.ibm.SOAP.requestTimeout=1800

         Note: Select the smallest timeout value that will meet your needs. Be prepared to wait for at least three times the timeout that you select—once to download files to the backup directory, once to upload the migrated files to the deployment manager, and once to synchronize the deployment manager with the migrated node agent.

      4. Go to the following location in the backup directory that was created by the WASPreUpgrade command:

         backupDirectory/profiles/profile_name/properties

      5. Open the soap.client.props file in that directory and find the value for the com.ibm.SOAP.requestTimeout property.

      6. Change the value of com.ibm.SOAP.requestTimeout to the same value that you used in the V6.1 file.

      Alternatively, you might want to consider a solution in which you specify -includeApps script in the WASPostUpgrade command when you migrate the deployment manager to V6.1 if one or both of the following are true for your situation:

      • You want to quickly migrate all nodes in the cell. After the entire cell is migrated, however, you are willing to manually run the application installation script for every application in the deployment manager backup directory and then synchronize the configuration with all migrated nodes.

      • You are able to run without any applications installed.

      Follow these steps to perform this alternative procedure:

      1. Specify -includeApps script in the WASPostUpgrade command when you migrate the deployment manager to V6.1.

      2. Migrate your entire cell to V6.1 before installing any applications.

      3. Run the wsadmin command to install each application.

         • Install the applications in the V6.1 configuration during normal operations or in applicable maintenance windows.

         • Specify -conntype NONE. For example:

           wsadmin -f application_script -conntype NONE

      4. Synchronize the configuration with all of the migrated nodes.

      See Migrating a large Network Deployment configuration with a large number of applications for more information on this alternative procedure.

    • When migrating a node from Version 5.x to V6.1, you see error messages similar to those in the following example:

      MIGR0304I: The previous WebSphere environment is being restored.
        java.lang.Exception: org.eclipse.emf.ecore.resource.Resource$IOWrappedException: 
        Class 'WASQueueConnectionFactory' not found. 
        (file:app_server_root/config/cells/cell_name/nodes/node_name/resources.xml, 7, 221)
      MIGR0286E: The migration failed to complete. 

      An incomplete or unsuccessful installation of internal messaging on the target node might cause the migration to fail in this way. If your resources.xml file is corrupted by a failed internal-messaging installation, for example, the file might not include the namespace information that the WebSphere Common Configuration Model (WCCM) needs during WASPostUpgrade command processing. Manually repair your resources.xml file.

      • If this error occurs when you migrate a V5.x standalone application server, perform the following actions:

        1. For your V6.1 application server, modify the app_server_root/config/cells/cell_name/nodes/node_name/resources.xml file so that it contains all of the required namespace information. For example, modify the xmi:XMI section at the top of the file to include the following information:

           xmlns:xmi="http://www.omg.org/XMI" 
           xmlns:resources.jms="http://www.ibm.com/websphere/appserver/schemas/5.0/resources.jms.xmi" 
           xmlns:resources.j2c="http://www.ibm.com/websphere/appserver/schemas/5.0/resources.j2c.xmi" 
           xmlns:resources="http://www.ibm.com/websphere/appserver/schemas/5.0/resources.xmi" 
           xmlns:resources.jms.internalmessaging="http://www.ibm.com/websphere/appserver/schemas/5.0/resources.jms.internalmessaging.xmi" 
           xmlns:resources.mail="http://www.ibm.com/websphere/appserver/schemas/5.0/resources.mail.xmi" 
           xmlns:resources.url="http://www.ibm.com/websphere/appserver/schemas/5.0/resources.url.xmi"
           

        2. Stop and restart the node.

        3. Rerun the migration.

      • If this error occurs when you migrate a V5.x federated node, perform the following actions:

        1. For your V6.1 deployment manager, modify the app_server_root/config/cells/cell_name/nodes/node_name/resources.xml file so that it contains all of the required namespace information. For example, modify the xmi:XMI section at the top of the file to include the following information:

           xmlns:xmi="http://www.omg.org/XMI" 
           xmlns:resources.jms="http://www.ibm.com/websphere/appserver/schemas/5.0/resources.jms.xmi" 
           xmlns:resources.j2c="http://www.ibm.com/websphere/appserver/schemas/5.0/resources.j2c.xmi" 
           xmlns:resources="http://www.ibm.com/websphere/appserver/schemas/5.0/resources.xmi" 
           xmlns:resources.jms.internalmessaging="http://www.ibm.com/websphere/appserver/schemas/5.0/resources.jms.internalmessaging.xmi" 
           xmlns:resources.mail="http://www.ibm.com/websphere/appserver/schemas/5.0/resources.mail.xmi" 
           xmlns:resources.url="http://www.ibm.com/websphere/appserver/schemas/5.0/resources.url.xmi" 

        2. Stop the node.

        3. Run the syncNode command on the node to synchronize it with the deployment manager.

        4. Rerun the migration.

    • 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 V5.x or 6.0.x is installed, you might not have run the WASPostUpgrade tool from the bin directory of the V6.1 installation root.

        1. Look for something like the following message to display when the WASPostUpgrade tool runs: IBM WebSphere Application Server, Release 5.0.

           This message indicates that you are running the WebSphere Application Server Release 5.0 migration utility, not the V6.1 migration utility.

        2. Alter your environment path or change the current directory so that you can launch the WebSphere Application Server V6.1 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.

           See WASPreUpgrade command.

        3. Retry the WASPostUpgrade tool.

      • An invalid backup directory might be specified.

        For example, the directory might have been a subdirectory of the V5.x or 6.0.x 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.

    • You decide that you need to run WASPreUpgrade again after you have already run the WASPostUpgrade command.

      During the course of a deployment manager or a managed node migration, WASPostUpgrade might disable the old environment. If after running WASPostUpgrade you want to run WASPreUpgrade again against the old installation, run the migrationDisablementReversal.jacl script located in the old app_server_root/bin directory. After running this JACL script, your V5.x or 6.0.x environment will be in a valid state again, allowing you to run WASPreUpgrade to produce valid results.

      For more information on scripting, see Getting started with scripting.

    • A federated migration fails with message MIGR0405E.The migration that has taken place on your deployment manager as part of your federated migration has failed. For a more detailed reason for why this error has occurred, open the folder your_node_name_migration_temp located on your deployment manager node under the ...DeploymentManagerProfile/temp directory. For example:

      /websphere61/appserver/profiles/dm_profile/temp/nodeX_migration_temp

      The logs and everything else involved in the migration for this node on the deployment manager node are located in this folder. This folder will also be required for IBM support related to this scenario.

    • V6.1 applications are lost during migration.

      If any of the V6.1 applications fail to install during a federated migration, they will be lost during the synchronizing of the configurations. The reason that this happens is that one of the final steps of WASPostUpgrade is to run a syncNode command. This has the result of downloading the configuration on the deployment manager node and overwriting the configuration on the federated node. If the applications fail to install, they will not be in the configuration located on the deployment manager node. To resolve this issue, manually install the applications after migration. If they are standard V6.1 applications, they will be located in the app_server_root/installableApps directory.

      To manually install an application that was lost during migration, use the wsadmin command to run the install_application_name.jacl script that the migration tools created in the backup directory. Use the following parameters:

      app_server_root/bin/wsadmin -f migration_backup_directory/install_application_name.jacl -conntype NONE

      See Wsadmin tool.

    • V6.1 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. Use the following parameters:

      app_server_root/bin/wsadmin -f migration_backup_directory/install_application_name.jacl -conntype NONE

      See Wsadmin tool.

    See WASPostUpgrade command.

• If you select the option for the migration process to install the enterprise applications that exist in the V5.x or V6.0.x configuration into the new V6.1 configuration, you might encounter some error messages during the application-installation phase of migration.

  The applications that exist in the Version 5.x or V6.0.x configuration might have incorrect deployment information—usually, 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 V5.x or V6.0.x 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 V6.1 configuration using the administrative console or an install script.

  V5.x node agents might display as not synchronized or not available when you change the deployment manager node name in a mixed cell during migration to the V6.1 deployment manager. V5.x node agents maintain a link to the V5.x deployment manager until they are restarted; therefore, they might fail to synchronize with the new deployment manager. The discovery problem, which prevents automatic synchronization, occurs because the node agent is not yet aware of the deployment manager name change that occurred during the migration. If you experience this problem, perform these steps on the node.

  1. Stop the node.

  2. Run the syncNode command.

  3. Restart the node.

  After migrating to a V6.1 cell that contains or interoperates with V6.0.x nodes that are not at V6.0.2.11 or later, the cluster function might fail. When starting these V6.0.x application servers, you might see the following problems:

  • You might see a first failure data capture (FFDC) log that shows a ClassNotFoundException error message. This exception is thrown from the RuleEtiquette.runRules method and looks something like the following example:

    Exception = java.lang.ClassNotFoundException
    Source = com.ibm.ws.cluster.selection.SelectionAdvisor.<init>
    probeid = 133
    Stack Dump = java.lang.ClassNotFoundException: rule.local.server
    at java.net.URLClassLoader.findClass(URLClassLoader.java(Compiled Code))
    at com.ibm.ws.bootstrap.ExtClassLoader.findClass(ExtClassLoader.java:106)
    at java.lang.ClassLoader.loadClass(ClassLoader.java(Compiled Code))
    at java.lang.ClassLoader.loadClass(ClassLoader.java(Compiled Code))
    at java.lang.Class.forName1(Native Method)
    at java.lang.Class.forName(Class.java(Compiled Code))
    at com.ibm.ws.cluster.selection.rule.RuleEtiquette.runRules(RuleEtiquette.java:154)
    at com.ibm.ws.cluster.selection.SelectionAdvisor.handleNotification(SelectionAdvisor.java:153)
    at com.ibm.websphere.cluster.topography.DescriptionFactory$Notifier.run(DescriptionFactory.java:257)
    at com.ibm.ws.util.ThreadPool$Worker.run(ThreadPool.java:1462)

  • You might see a java.io.IOException that looks something like the following example:

    Exception = java.io.IOException
    Source = com.ibm.ws.cluster.topography.DescriptionManagerA. update probeid = 362
    Stack Dump = java.io.IOException
    at com.ibm.ws.cluster.topography.ClusterDescriptionImpl.importFromStream(ClusterDescriptionImpl.java:916)
    at com.ibm.ws.cluster.topography.DescriptionManagerA.update(DescriptionManagerA.java:360)
    Caused by: java.io.EOFException
    at java.io.DataInputStream.readFully(DataInputStream.java(Compiled Code))
    at java.io.DataInputStream.readUTF(DataInputStream.java(Compiled Code))
    at com.ibm.ws.cluster.topography.KeyRepositoryImpl.importFromStream(KeyRepositoryImpl.java:193)

  During migration, V6.1 cluster information is distributed throughout the cell. V6.0.x nodes that are not at V6.0.2.11 or later fail to read this information.

  To avoid this problem, upgrade all V6.0.x nodes that will be contained in or interoperating with a V6.1 cell to V6.0.2.11 or later before migrating your deployment managers to V6.1.

What to do next

If you did not find your problem listed, contact IBM support.