Migration App Common Issues and Workarounds

Audience

Any user of Migration App.

Context

We’ve observed some common issues and questions arising during the everyday use of Migration App. Many of these minor issues can easily be remedied by taking specific actions and don’t require a Support Ticket. But never hesitate to send an email to support@egnyte.com if you would like some assistance.

Common Error Codes and Issues

• DB Lock Issue: Error Code #2100
• Disk Space Error: Error Code #6080
• Improving Slow Performance
• Registration Failed
• Access Denied to Folders During Scan
• WebSocket: close 1006 (abnormal closure): unexpected EOF
• Permissions Migration Error - "directory not found on source"
• True-Up Error “destination newer than the source”
• DB Lock “index.pmt missing”: Error Code #2100
• System free memory is too low: Error Code #5050
• Maximum Job Size Exceeded: Error Codes #629 and #631
• Migration Job Auth Failure: Error Code #401
• Migration App is Not Accessible
• Agent Upgrade Failure
• Migration App - Network Drives - Not Detected
• Resource Constraints Not Displayed While Installing Migration App Agent on Windows 10

DB Lock Issue: Error Code #2100

1. Go to the egnyte-agent folder (Path C:\Users\[username]\AppData\Local\egnyte-agent\[migration-id])
2. Navigate to migration folder  🡪  diskhash folder  🡪  mmap folder
3. Find a .lock file at this path
4. First kill the CMM Agent service manually, which should delete this file
5. If the file is not deleted automatically, you can delete it manually
6. Start the CMM Agent service again
7. Initiate migration again

Disk Space Error: Error Code #6080

1. By default, you need a minimum of 10GB free space on the hard disk. 
2. Manually clean up or delete a few unused migrations or any other data on the Windows Host machine that might be unnecessarily consuming disk space. 
3. If freeing up disk space is not possible, set a reduced minimum space value required in a custom configuration file and upload it to the Agent.
   

   - Advanced Mode must first be enabled for the domain to make this feature available. If it is not yet enabled, submit a ticket to support@egnyte.com to set enable Advanced Mode for the domain.
   - This approach can lead to other complications like slowness during data migration, so this can be treated as a last resort.

4. In the configuration file, you can change the “min_diskspace_required” value to between 5 and 9. Any value less than 5GB is not recommended. 
5. More information about the custom configuration file for the Agent is documented here.

Improving Slow Performance

1. To improve the speed of both scanning and migration, the number of threads can be increased. 
2. There are two kinds of threads:
   1. Transfer threads - will impact the speed of Data Migration and True-Ups
   2. Checkers threads - will impact the speed of scanning
      

      - This approach creates extra threads, so it increases memory and CPU consumption on the Windows Host machine where the agent is installed. This will not be an effective option unless the Host machine has sufficient compute resources.
      - Advanced Mode must first be enabled for the domain to make this feature available. If not enabled, submit a ticket to support@egnyte.com to enable Advanced Mode for your domain.

3. Under Advanced Options from the Migration Details page you will now be able to see Threads as an option.
   
   
   
   
4. Increase the Transfers and Checkers, then re-run the job. Make sure to increase the num by in multiples of two. And Checkers should always be double the figure for Transfers.

More information about Controlling Threads is available in the Advanced Mode in Migration App article.

Registration Failed

1. When registering a new Agent, you may see an error message of Registration Failed on the System Tray.
2. Check the system tray app logs. You can find them located on the Windows Host machine at pathC:\ProgramData\egnyte-agent\logs.
   
   
   
   
3.  Check the logs for the following error:
   

   Multiple connections to a server or shared resource by the same user, using more than one username, are not allowed. Disconnect all previous connections to the server or shared resource and try again.

   
   
   
   
4. Solution: There are two options to solve for this:
   1. Open the Task Manager on the Windows Host and check to see if the cmmagentservice is already in a running state. If it is running, stop and restart the Windows machine. Then try to connect again using the System Tray App.
   2. If this doesn’t work, you can follow the steps described here.

Access Denied to Folders During Scan

1. This error occurs when the Migration Job is running a scan, but the Migration Operator who registered the Agent is using and admin account that does not have permission to access the files which need to be migrated.
2. The error will be displayed in the Migration Report.
   
   
   
   
3. If the Migration Operator has created a migration with a source folder which is stored on a network-mapped drive, we need to ensure that user has sufficient permissions to access the source folder on this network. 
4. When using a mapped drive, we need to make sure to use UNC path as a source folder path \\?\UNC\server\shared-folder\file

WebSocket: close 1006 (abnormal closure): unexpected EOF

If this occurs, the Migration Operator will only be able to see the Agent has been disconnected from the cloud.

In Egnyte’s backend diagnostic logs, this will appear as an error reading the message on WebSocket connection for agent: “Listen Err: websocket: close 1006 (abnormal closure): unexpected EOF.” Your support Agent can confirm this is being reported for your migration job.

This is a transient error that usually occurs when the Agent gets disconnected from the Egnyte Control Plane. This can happen when:

1. There is no internet connectivity, which can be solved by checking the connection.
2. There is a deployment happening on the Egnyte Control Plane side. If you have already confirmed you have internet connectivity, open a Support ticket (by emailing ticket to support@egnyte.com) to request they check with Engineering to confirm if a deployment is in progress.

In both of the cases described above, you can retry after some time and Migration App should work as expected. If the error persists for more than 30-45 minutes, then there is a potential bug that needs to be reported by opening a ticket to support@egnyte.com.

Permissions Migration Error “directory not found on source”

While doing permissions migration, you might receive an error “directory not found on source“ for some of the files.  You will find this reported in the Migration Report. It will occur in the following instances:

1. All paths delivering this error message have a path length more than 256 characters
2. Default windows has path length limit of 256 chars, as described here.
3. Although, Egnyte supports a maximum path length of 1,000 characters, the Windows default limit of 256 characters is the limiting factor.

In this case, there are two solutions. 

1. Change the default path length by changing the registry key to enable Windows Long Path, as described here.
2. Change the folder structure on the source so that the path length remains under 256 chars. Once you have completed restructuring:
   • Run Scan again.
   • Run a True-up to upload the data according to new folder structure.
   • Run Permission Simulation.
   • Run Migrate Permissions.

True-Up Error “destination newer than the source”

While running a True-up, you may encounter a situation where the file on the destination (Egnyte) has newer modified date than the file on the Source. As a result, the file will skipped with “destination newer than the source” annotation recorded in the Migration Report. 

For Migration App to run properly, data should never be modified on Egnyte between the last Scan command and a True-up command.

Error Code 2100 (DB Lock) “index.pmt missing”

This may occur because the CMM Agent installed on your Windows Host machine uses a local database to maintain some state, and this local database has become corrupted. In such a case, you would see this error displayed on the Migration Details UI.

You can resolve this easily by following these instructions:

1. Kill the CMM Agent service manually
2. Go to the egnyte-agent folder (Path C:\Users[username]\AppData\Local\egnyte-agent[migration-id])
3. Inside migration folder 🡪  diskhash folder 🡪  mmap folder 🡪  tmppffl folder
4. Inside this, there are in total three folders. Delete all three folders.
5. Start the CMM Agnet service again
6. Make sure Confluence is turned off in Advanced Options for this migration job. 
7. Initiate migration again

This will create a new database for the migration, which should take less than a day for mid-sized or small migration jobs. It can take longer for larger jobs.

Error Code #5050 (system free memory is too low)

5050 is a generic error code that is displayed when the Migrate Data command fails. On the Migration Report, you may see the following error “system free memory is too low. Please free memory to continue migration”.

1. Check the migration report for the reason for the failure. 
2. In the example above, we can see migration command was aborted due to low memory (RAM) on the Windows Host. 
3. To resolve this, you have a few options:
   1. Open Task Manager and check which processes are consuming excessive RAM. 
   2. Shut down any unnecessary applications running on the Windows Host. 
   3. Rerun the migration command.

Error Codes #629 and #631: Migration Job Size Exceeded

1. Migration jobs will not proceed if the job size (either the number of files or GB size) exceeds the limits set for your domain. In these situations, you would see either error code 631 or 629 on the Migrations Details page.
2. Occasionally, this can happen without any indication being presented on the UI or the Migrations Report. In such cases, you can submit a ticket to support@egntye.com to confirm the cause by checking our backend logs.
3. Solution:
   1. If it is the first time running the job, it’s recommended to break the job into smaller tasks to ensure they stay within the default limits. Find recommended limits here. However, if this occurs during True-Up, restructuring data on the source is not recommended. See Option 2.
   2. Alternatively, you may be able to request an increase in the limits for your domain. See this article for more context.

Error Code #401: Migration Job Auth Failure

Migration jobs sometimes fail due to authentication failure. This can happen when the migration job is running for a long period and the Migration Operator did not log into the Migration App for some time (more than 8 hours).

The only solution to this problem is for the User to log into Egnyte, go to Migration App and refresh the UI. This will refresh the necessary authentication token and user can re-start their migration jobs.

As a general rule, Migration Operators should revisit the Migration App periodically if any migration jobs are running. In the future, we will send email notifications if an authentication failure occurs.

Migration App is Not Accessible

If Migration App has been accessed previously, all domain Admins should be able to access it by selecting Migration from the app picker menu. Once on the Landing Page, two blue On-Prem Migration buttons should be displayed. Clicking either will take the User to the Migration Dashboard.

If Migration App has never been accessed previously, any Admin on a Platform Plan can gain access by clicking the button labeled Request Enablement for My Domain. This will take you through a wizard. More information can be found in Accessing Migration App.

If you want to make Migration App available to Power Users on your domain, see Enabling Power Users to Use Migration App.

If Migration App had been previously accessed, but is currently not available, submit a ticket to support@egnyte.com to analyze the root cause.

Agent Upgrade Failure

Occasionally, the Agent auto-upgrade is unsuccessful. This can happen when a Windows Host machine restart is pending.  

In this case, simply restart the Windows Host machine where the Agent is installed. Every hour, our back end triggers another upgrade cycle, so within an hour your Agent should be upgraded.

Migration App - Network Drives - Not Detected

This issue can be experienced multiple ways:

• Network paths cannot be viewed or selected while using the Migration App
• Migration App can detect the local drives but network drives S and H do not show up even though the network drives an be seen in Windows File Explorer

The reason for this is that the Agent is unable to access path due to permissions or credential limitations. 

To resolve this, the same user (Admin) should run CMMAgent services and mount the network drive so as to be able to access the network drive.

Resource Constraints Not Displayed While Installing Migration App Agent on Windows 10

Users may encounter an error while installing the Migration App Agent on Windows 10 systems with insufficient resources.

This issue is mainly attributed to the Windows 10 system's inability to accurately retrieve resource information. This is typically due to complications with the WMIC BIOS interface, which can be a symptom of deeper issues such as inconsistencies in software, firmware, or driver updates that lead to system instability and prevent successful software installations.

Troubleshooting Steps:

1. Gather System Information:
   • Press Windows Key + R to open the Run dialog.
   • Type msinfo32 and press Enter to open the System Information tool.
   • In the System Information window, go to File > Save and save the file.
   • Provide the file to Egnyte support for analysis.
2. Check Disk Space:
   • Press Windows Key + R to open the Run dialog.
   • Type cmd and press Enter to open the Command Prompt.
   • Execute the following command:
     

     arduino
     wmic logicaldisk where "DeviceID='C:'" get DeviceID, FileSystem, FreeSpace, Size

Customer Action Steps: If you are comfortable with command line operations and basic troubleshooting, you can perform the following actions to resolve the issue:

1. Run a clean update to exit any update loop.
   • Execute Sfc /scannow to scan and repair system files.
   • Use DISM tool commands to check the health of the system image and restore it if necessary.
   • Reset Windows Update components using the following commands:
     

     arduino
     
     net stop wuauserv
     
     net stop cryptSvc
     
     net stop bits
     
     net stop msiserver
     
     ren C:\Windows\SoftwareDistribution SoftwareDistribution.old
     
     ren C:\Windows\System32\catroot2 catroot2.old
     
     net start wuauserv
     
     net start cryptSvc
     
     net start bits
     
     net start msiserver
     
     pause

2. Reboot the system and attempt to run Windows updates.
3. If updates lead to a loop, use the Windows Update Assistant for assistance.
4. Post-update, run Sfc /scannow again to ensure all system files are intact and repaired.
5. Attempt to reinstall the Migration App Agent with administrative privileges.

If the above steps do not resolve the issue, or you are not comfortable performing these actions, schedule a call with our Support team to assist with troubleshooting.

Questions? Feature Requests? Other Feedback?

If you have feature requests or suggestions, feel free to submit them on our Product Board, and be sure to mention Migration App in the text.

For more complex requests that would benefit from providing screenshots or other attachments, you may submit them to support@egnyte.com. Be sure to include Migration App in the email title. Our Support team will push your comments to the Product team for consideration.