Troubleshoot migration

 

+

Search Tips   |   Advanced Search

• While you are using the Version 6.1 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 WAS 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...

     migration_backup_dir/WASPreUpgrade.time_stamp.log
     profile_root/logs/WASPostUpgrade.time_stamp.log
     app_server_root/logs/clientupgrade.time_stamp.log

     If the migration failed to complete, 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.

  4. With WAS running, run the dumpNameSpace command and pipe, redirect, or "more" the output so that it can be viewed.

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

  5. If the object a client needs to access does not appear, use the 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.

  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 WAS 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 console.

      The console no longer displays deprecated JDBC provider names. The new JDBC provider names used in the 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 WAS 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 WAS, Release 5.0.

           This message indicates that you are running the WAS 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 WAS 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 WAS 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 WAS 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 WAS 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 the configuration. For example, the following entry would give you a timeout value of a half of an hour:

         com.ibm.SOAP.requestTimeout=1800

         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 ND configuration with a large number of applications for more information on this alternative procedure.

    • When migrating a node from V5.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 appserver, perform the following actions:

        1. For your V6.1 appserver, 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 WAS 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 WAS, Release 5.0.

           This message indicates that you are running the WAS 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 WAS 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 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. In a Linux environment, for example, use the following parameters:

      ./wsadmin.sh -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. In a Linux environment, for example, use the following parameters:

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

      See Wsadmin tool.

    See WASPostUpgrade command.

• When you use the Migration wizard to migrate a profile from WAS V6.0.2 to Version 6.1.x on a Solaris x64 processor-based system, the migration might fail during the WASPostUpgrade step. You might see messages similar to the following in profile_root/logs/WASPostUpgrade.time_stamp.log:

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

  WebSphere Application Server V6.0.2 uses a JVM in 32-bit mode. The Migration wizard for WAS V6.1.x calls the WASPostUpgrade.sh script, which attempts to run the JVM for V6.0.2 in the 64-bit mode when the server stops the V6.0.2 node. Complete the following actions to remove the incomplete profile and enable WAS to correctly migrate the Version 6.0.2 profile:

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

     cd /opt/IBM/WAS/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 V6.1.x 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 V6.1.x 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 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 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 appservers, 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.

• After you migrate a managed node to V6.1, the appserver might not start. When you try to start the appserver, you might see errors similar to those in the following example:

  [5/11/06 15:41:23:190 CDT] 0000000a SystemErr R com.ibm.ws.exception.RuntimeError: com.ibm.ws.exception.RuntimeError: org.omg.CORBA.INTERNAL: CREATE_LISTENER_FAILED_4 vmcid: 0x49421000 minor code: 56 completed: No
  [5/11/06 15:41:23:196 CDT] 0000000a SystemErr R at com.ibm.ws.runtime.WsServerImpl.bootServerContainer(WsServerImpl.java:198)
  [5/11/06 15:41:23:196 CDT] 0000000a SystemErr R at com.ibm.ws.runtime.WsServerImpl.start(WsServerImpl.java:139)
  [5/11/06 15:41:23:196 CDT] 0000000a SystemErr R at com.ibm.ws.runtime.WsServerImpl.main(WsServerImpl.java:460)
  [5/11/06 15:41:23:196 CDT] 0000000a SystemErr R at com.ibm.ws.runtime.WsServer.main(WsServer.java:59)
  [5/11/06 15:41:23:196 CDT] 0000000a SystemErr R at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
  [5/11/06 15:41:23:196 CDT] 0000000a SystemErr R at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:64)
  [5/11/06 15:41:23:197 CDT] 0000000a SystemErr R at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)

  Change the port number at which the managed node's appserver is listening. If the deployment manager is listening at port 9101 for ORB_LISTENER_ADDRESS, for example, the appserver of the managed node should not be listening at port 9101 for its ORB_LISTENER_ADDRESS. To resolve the problem in this example, perform the following steps:

  1. From the console, click Application servers > server_name > Ports > ORB_LISTENER_ADDRESS .

  2. Change the ORB_LISTENER_ADDRESS port number to one that is not used.

• If synchronization fails when you migrate a managed node to V6.1, the appserver might not start. You might receive messages similar to the following when you migrate a managed node to V6.1:

  ADMU0016I: Synchronizing configuration between node and cell.
  ADMU0111E: Program exiting with error:
             com.ibm.websphere.management.exception.AdminException: ADMU0005E:
             Error synchronizing repositories
  ADMU0211I: Error details may be seen in the file:
             /opt/WebSphere/61AppServer/profiles/AppSrv02/logs/syncNode.log
  MIGR0350W: Synchronization with the deployment manager using the SOAP protocol 
   failed.
  MIGR0307I: The restoration of the previous WAS 
   environment is complete.
  MIGR0271W: Migration completed successfully, with one or more warnings.
  

  These messages indicate the following:

  • Your deployment manager is at a V6.1 configuration level.

  • The managed node that you are trying to migrate is at a V6.1 configuration level on the deployment manager's repository (including applications).

  • The managed node itself is not quite complete given that you did not complete the syncNode operation.

  Perform the following actions to resolve this issue:

  1. Rerun the syncNode command on the node to synchronize it with the deployment manager.

  2. Run the GenPluginCfg command.

 

What to do next

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

---