Troubleshooting errors
Each time the JumpCloud ADMU is ran new logs are appended to the C:\Windows\Temp\jcadmu.log file.
The latest version of the ADMU will throw specific error messages to help determine the terminating reason for a failed migration.
The log messages can help deduce why a migration was unsuccessful. There are several reasons why a migration might fail. The most common of these is that the migration user (the user being migrated) has a service or process loaded in memory before or during migration. If that's the case, typically restarting, logging into an administrator account and re-attempting migration can solve the issue. Depending on the exact issue however additional work may be required.
The JumpCloud ADMU relies heavily on access to the user's registry hive. The two files that the tool commonly accesses while migration is underway are the C:\Users\someUser\NTUSER.DAT & C:\Users\someUser\AppData\Local\Microsoft\Windows\UsrClass.dat files. Both of these must be closed and accessible for a successful account migration. Logging in as the migration user will load both of these files into memory and lock them. These files can also become locked by:
- Automated process or services with the user's cached credentials launching during migration
- The user logging into the device during migration
- A scheduled task launching with the user's cached credentials
If at any point another service loads and locks these files an attempted migration will typically fail. This is fine, the tool should attempt to place the computer back in the state it was in before migration so migration can be re-attempted. The only exception to this is the case where an AntiVirus application halts migration or false flags the tool as malicious during migration.
The load/unload error is expected when the tool does not have access to the user's NTUSER or UsrClass files.
The registry copy error can be encountered when the tool does not have access to the user's NTUSER or UsrClass files.
If the tool exits and fails to throw the registry copy error, it's likely the case that an AntiVirus application has halted further code from executing.
During migration, the ADMU invokes reg.exe to copy a backup version of the AD user's NTUSER and UsrClass registry hives into a newly created local user account. This action can be considered suspicious depending on the various AntiVirus software vendors.
The registry backup error can occur near the beginning of migration, it's one of the first steps taken before the tool attempts to write to a new user profile.
If the C:\Users\someUser\NTUSER.DAT and/or C:\Users\someUser\AppData\Local\Microsoft\Windows\UsrClass.dat files are inaccessible, missing or read-only then the registry backup error can be thrown.
The registry rename error can be encountered if one of the required NTUSER or UsrClass files can not be found, accessed or written.
During migration, a backup of the migration user's NTUSER.DAT and UsrClass.dat files are made. The copied version of the files are renamed with a timestamped tag in the event migration needs to be reverted or a migration fails.
If a user was migrated on Aug 10, 2024 they would have a backup file written to their registry hive directories with a similar name:
NTUSER_original_2024-08-10-145323.DAT UsrClass_original_2024-08-10-145323.dat
If the C:\Users\someUser\NTUSER.DAT and/or C:\Users\someUser\AppData\Local\Microsoft\Windows\UsrClass.dat files are inaccessible, missing or read-only then the registry rename error can be thrown.
The user creation error can be thrown if the ADMU fails to create the specified user. If this error is encountered it's likely the case that the user specified already exists on the local system. The GUI version of the tool will prevent you from beginning migration but the PowerShell scripted version of the tool will error if the user already exists.
To determine if a user already exists, open the Windows menu on the local device and search for lusrmgr.msc. Delete the local user from the system. Delete the C:\Users\someJumpCloudUserName (where someJumpCloudUserName is the new local user, not the AD user to be migrated) profile directory before running the ADMU again.
The user initialization error can occur if the user running ADMU doesn't have Administrator permission. If this error is encountered, ensure the user does not exist with lusrmgr.msc, delete the C:\Users\someJumpCloudUserName (where someJumpCloudUserName is the new local user, not the AD user to be migrated) profile if for some reason it exists and re-attempt migration as an Administrator.
The user folder redirection error can occur if the user to be migrated have one of their main folders (Desktop, Documents, Downloads, Music, Pictures, Videos, Favorites) redirected to another location such as a network shared drive for example: \\192.168.50.78\SharedFolder\USERNAME\Desktop. If the issue is encountered, you can either:
-
Use
-ValidateUserShellFolder $falseparameter (CLI only) onStart-Migrationto ignore the folder/directory validation. Use this parameter with caution. After migration, the user will encounter a shared folder error and will need to provide account credentials to restore their shared folders -
Ensure that the redirected folders are set to the default path by:
- Sign in to the user
- Right-click on the folder that has a redirected path in File Explorer and select Properties.
- Click on the Location tab.
- Click on the Restore Default button.
- Click on Yes to confirm the change.
- Click on OK to close the Properties window.
