Discovery tool troubleshooting guide

Discovery tool and the Migration Toolkit for Application Binaries

The Transformation Advisor Discovery tool uses a tool called the Migration Toolkit for Application Binaries. You may use the binary scanner directly. This may be particularly useful in some troubleshooting scenarios. For information on how to download and use the Migration Toolkit for Application Binaries please click here.

Failed to upload collection zip file to Transformation Advisor server

After the discovery tool gathers the configuration information for an application, it will create a zip file and try to upload it to the Transformation Advisor server. If it cannot reach the server, you may see the following error message:

Current Operation: Error occurred: Problem connecting with server See log for details.

To work around this problem, you can get the collection zip file from the discovery tool directory and manually upload it to the Transformation Advisor server through the Collection page in the UI.

WebSphere profile <profile_name> does not exist

This message displays when the discovery tool cannot find the input profile name from the WAS profile registry. Verify that the input profile name is correct by checking the WS_PROFILE_REGISTRY defined in the $WAS_HOME/properties/wasprofile.properties file.

The default profile registry xml file is:
WS_PROFILE_REGISTRY=${was.install.root}/properties/profileRegistry.xml

If your profile registry xml file is not using the default file, create a symbolic link from $WAS_HOME/properties/profileRegistry.xml to the location of the real profile registry file.

Incorrect context root for web applications on WebSphere detected by discovery tool

In Transformation Advisor version 1.9.4 and later, the discovery tool detects the context root for web applications running on WebSphere. The context root of the application is used in deployments on Liberty to simplify access to the application. If the context root is not appropriate, a page with the following error message is displayed when accessing the deployed application:

Context Root Not Found.

To work around this problem, update the Helm chart for the application in the Git repository:

  1. Clone the Git repository containing the Helm chart for the application.
  2. Edit the file chart/[application name]/values.yaml and change the rewriteTarget to "/" as shown:
ingress:
  enabled: true
  rewriteTarget: "/"
  1. Commit and push the changes to the Git repository.
  2. Wait for the application to be re-deployed. The ingress path for the application now redirects to the Liberty base page. You can access the application by appending the context root of the application to the ingress path.

For example, if the ingress path is modresorts and the context root for the application is resorts, the URL to access the application would be http://[OCP public IP]/modresorts/resorts/.

Discovery tool fails to generate server.xml artifacts

If the discovery tool is run by a user other than the user that has launched the deployment manager, it will fail to generate the server.xml artifacts. The collected artifacts will look like a collection that has not requested configuration analysis. On Transformation Advisor versions earlier than 1.9.4, you may see the following error:

Exception in thread "main" java.io.FileNotFoundException: <some_path>_server.xml (A file or directory in the path name does not exist.) at java.io.FileInputStream.<init>(FileInputStream.java:113) at java.io.FileInputStream.<init>(FileInputStream.java:73) ... ...

You must run the discovery tool as the same user who has launched the deployment manager. You can check which user that is by using the ps command.

Note: If you have already unpacked the discovery tool as a different user, you may need to edit the permissions or owner for the unpacked discovery tool directory before you run it as the new user. Alternatively you can simply unpack the discovery tool again as the new user.

Checksum error trying to extract the discovery tool

If a checksum error is returned after trying to extract the discovery tool, try this workaround:

gzip -d transformationadvisor-<OperatingSystem>_<workspace>_<collection>.tgz
tar xf transformationadvisor-<OperatingSystem>_<workspace>_<collection>.tar

Error when running the discovery tool in non-English locales

If you see Connecté au processus dmgr sur le noeud ... (or something similiar) when running the the discovery tool with the command /data/WebSphere/AppServer/profiles/Dmgr01/bin/wsadmin.sh -user wasadmin -password wasdm1i -lang jython -c "AdminApp.list()", try the following work around:

In the terminal where you are running the discovery tool, type:

export LANG=C

Then run the discovery tool command again and it should bypass the problem.

The binary scanner ignores com.ibm packages

The discovery tool can be configured to ignore certain packages. Check the customCmd.properties file in $TA_HOME/conf directory to verify. If there are any packages that are ignored, you can uncomment the line and modify the command to include them. The discovery tool will include uncommented commands when invoking the binary scanner.

The discovery tool skips managed profiles when run against a specified profile

Managed profiles are skipped because a copy of their configuration is held on the dmgr. Running on the dmgr should solve this issue.

The discovery tool skips the applications that were installed using zero binary copy mode when run against a specified profile

Applications that were installed with zero binary copy mode are skipped because the discovery tool can't get all of the required configurations for the applications to generate the migration analysis. This type of application must be manually evaluated to determine the migration effort.

Running the discovery tool produces a libjvm.so failed to load: error

This error can be caused when Java cannot find the correct libraries. Use the Java version on the machine itself instead of the one that is downloaded with the discovery tool. Complete the following steps to resolve this error:

  1. Check to see if the wsadmin is owned or run by a specific user. If it is, then that same user should run the discovery tool.
  2. Make sure that the user has read, write, and execute permissions to the location where you have unpackaged the discovery tool.

Make sure you are using the version of Java that is on the machine:

  1. cd into transformationadvisor-2.1
  2. Replace the JRE directory with the JRE directory from the WAS machine itself.
  3. Run the discovery tool command again.

Error during upload - Incompatible files detected

The discovery tool produces reports that are linked to each application. If you see this error, it means that one or more applications were not processed correctly and the step to link the report to an application has failed.

You can resolve this issue as follows:

  1. Unpackage the profile.zip file.
  2. Delete files with the following names: InventoryReport.json, InventoryReport.html, AnalysisReport.json, AnalysisReport.html, TechnologyReport.json, TechnologyReport.html
  3. Manually upload the zip file to Transformation Advisor through the UI.

To determine if you are missing any applications:

  1. Get the list of applications in Transformation Advisor.
  2. Look at the profiles directory in WAS_HOME to review the full list of applications installed in that profile.
  3. Identify applications in the profile that are missing from Transformation Advisor.

Untar failed after downloading the discovery tool and copying it over to a Linux VM

Try the following commands instead:

gzip -d transformationadvisor-2.1_Linux_xxxxxx.tgz
tar xf transformationadvisor-2.1_Linux_xxxxx.tar

Unable to download the migration files after data upload

If you upload a zip file from the discovery tool to the Transformation Advisor UI but are unable to download the migration bundle or any migration files, you'll need to run a full analysis so that Transformation Advisor can get the server configuration. Run the following command:

bin\transformationadvisor.bat -w <WEBSPHERE_HOME_DIR> -p <PROFILE_NAME>

Then try the upload again.

Windows discovery tool does not work if WebSphere home contains a space in the path

If you run the Windows discovery tool with the following command:

bin\transformationadvisor.bat -w "C:\Program Files (x86)\IBM\WebSphere\AppServer" -p AppSrv01

The discovery tool might throw an error message. Complete the following to resolve the issue:
Open command prompt and go to the directory which you want to know the short path

Type dir /x

Run the discovery tool with the shortcut name, for example:

bin\transformationadvisor.bat -w "bin\transformationadvisor.bat -w "C:\PROGRA~2\IBM\WebSphere\AppServer" -p AppSrv01

Windows discovery tool does not work after extracting to default path

If you run the Windows discovery tool with the bin\transformationadvisor.bat -w "C:\Program Files\IBM\WebSphere\AppServer" -p AppSrv01 admin admin command and see the following output:

Screenshot showing the command console with the message that the input line is too long

The path for TA_HOME is too long. To work around this issue, uncheck the option to use the file name as the subdirectory as the path already contains the transformationadvisor-2.1 subdirectory when you unpackage the discovery tool zip file. When this box is unchecked, the discovery tool will unzip to: C:\Users\Administrator\TA\DC\transformationadvisor-2.1

Screenshot showing how to uncheck the option in the extract tool to use the file name as the subdirectory

Steps to run the discovery tool on a z/OS environment

NOTE: Running the discovery tool on a z/OS environment has been tested with bash versions 4.2 and 4.3

  1. It is recommended that the discovery tool be run from an ssh session, and not the Unix System Services OMVS shell since the discovery tool uses screen refresh in ways that don't work on 3270-type devices.
  2. Install bash if it's not already available and make sure it is added to the system path, e.g. export PATH=/usr/bin/rocket/bash-4.3/bin:$PATH
  3. Install gunzip if it's not already available, e.g. from Rocket Software
  4. sftp / download the discovery tool file transformationadvisor-zOS.tgz to the z/OS machine
  5. Extract the .tgz file, e.g. by running: gunzip -c transformationadvisor-zOS.tgz | tar xf -
  6. Ensure that the ownership of the transformationadvisor-2.X.X folder is that of the user that will later run the discovery tool. If necessary, change permissions and ownership of the transformationadvisor-2.X.X folder by running:
chown -R <user> transformationadvisor-2.X.X
  1. Change directory to the transformationadvisor-2.X.X folder, add that to the system path
  2. Run (from regular shell, NOT from bash): cd bin && . ./zOSPrereq && cd ..
  3. To see all the run options: bin/transformationadvisor --help . The first time the discovery tool runs, there will be a license agreement text to review. If a memory-related issue occurs, add the -J-Xmx512m option, i.e. bin/transformationadvisor -J-Xmx512m --help
  4. (This step is not required from Transformation Advisor 3.0 onwards) If user defined rules are used (a feature only available from Transformation Advisor 2.5.0), note that all files within the conf/userDefinedRules are in UTF-8 and need to be kept in that encoding. Therefore, to use this feature in z/OS, work with the files in UTF-8 in another system and then copy them back in.
  5. Run the discovery tool, for example: bin/transformationadvisor -w <WAS home> or bin/transformationadvisor -w <WAS home> -p default
  6. The discovery tool will produce a zip file, e.g. default.zip, that can be uploaded to the IBM Cloud Transformation Advisor UI for viewing the results.

.