Troubleshooting USMT: Common User State Migration Issues in Windows Client

Table of Contents

When managing Windows client deployments, the User State Migration Tool (USMT) 10.0 is invaluable for transferring user profiles and data. However, migration processes can sometimes encounter unforeseen issues. This guide provides comprehensive troubleshooting steps for common problems experienced with USMT, emphasizing the critical role of log files in diagnosing and resolving errors.

Understanding the detailed information within USMT log files is the first and most crucial step in any troubleshooting effort. These logs contain not only USMT-specific error messages but also Windows application programming interface (API) errors, which can pinpoint the exact cause of a migration failure.

General Guidelines for Identifying Migration Problems¶

Effective troubleshooting begins with a structured approach to problem identification. When a problem or error message surfaces during the migration process, consider the following general guidelines to accurately determine the source and implement an appropriate solution. Thorough investigation of logs and environmental factors can significantly reduce diagnostic time.

Utilizing USMT Log Files for Diagnosis¶

The ScanState, LoadState, and UsmtUtils logs are invaluable resources for pinpointing exact USMT error messages and Windows API error messages. These logs are often the first place to look when a migration fails, as they contain granular details about each step of the process. For deeper insights into USMT return codes and their meanings, consult the official documentation on return codes, which provides a comprehensive list of error indicators. Additionally, Windows system error codes, identified in the logs, can be further investigated by typing net.exe helpmsg <error_number> in a command prompt window, revealing detailed descriptions of the underlying system issues.

We highly recommend using the /v:5 option when initially testing your migration. This verbosity level generates a highly detailed log file, which, although large, provides extensive information crucial for diagnosing failures. While this level of verbosity can be adjusted for production migrations, reducing it may complicate the diagnosis of issues encountered in a live environment. For advanced debugging, you can even set the verbosity level higher than 5 to direct log file output to a debugger, offering an even more granular view of the migration process.

Verifying and Extracting from Migration Stores¶

The UsmtUtils tool is essential for managing your compressed migration stores. You can use the /Verify option with UsmtUtils to check the integrity of files within a compressed migration store. This step is vital to ensure that no corruption occurred during the data collection or storage process, which could lead to data loss or migration failures during the restore phase.

Furthermore, if you need to access specific files from a compressed migration store, the /Extract option with UsmtUtils allows you to do so. This functionality is particularly useful for recovering individual files or verifying the contents of the store without performing a full LoadState operation. Both /Verify and /Extract are powerful utilities that enhance the reliability and flexibility of your USMT deployment.

Monitoring Progress and Environment Details¶

Creating a progress log using the /Progress option helps monitor the migration in real-time, offering insights into the current stage of the process. This log can be a useful indicator of where the migration might be stalling or encountering issues, providing a high-level overview of the operation’s flow.

It is also crucial to gather comprehensive operating system information and application versions from both the source and destination computers. This includes details about Internet Explorer, Microsoft Office, and any other relevant programs. Documenting the exact steps required to reproduce the problem in a testing environment can significantly aid in identifying the root cause, allowing for a systematic approach to resolution and validation of fixes.

Post-Migration Actions and Application Closure¶

After successfully running the LoadState tool, it is important to instruct users to sign out and then back into their accounts. Some migrated settings, such as fonts, desktop backgrounds, and screen-saver configurations, will only take effect after the next user logon. This is a common oversight that can lead to false positives when evaluating the completeness of a migration.

Finally, always ensure that all applications are closed before executing the ScanState or LoadState tools. If applications are running during the migration process, USMT might not be able to migrate certain data, leading to incomplete or corrupted user profiles. For instance, if Microsoft Outlook is open, USMT may fail to migrate associated PST files, resulting in missing email archives. By default, USMT will fail if it cannot migrate a file or setting; however, using the /c option allows USMT to ignore errors and continue, though it will log any files that were in use and not migrated.

User Account Problems¶

User account migration is a core function of USMT, but it can present several challenges. Understanding the common pitfalls related to user accounts is key to ensuring a smooth and complete migration.

Issues with Local Account Creation¶

Problem: “I’m having problems creating local accounts on the destination computer.”

Resolution: USMT can manage the migration of user accounts, including local accounts. For detailed instructions on how to effectively create and migrate local user accounts, refer to the official USMT documentation on migrating user accounts. This resource provides specific configurations and best practices to ensure successful local account transfer and setup on the destination machine.

Incomplete User Account Migration¶

Problem: “Not all of the user accounts were migrated to the destination computer.”

Causes/Resolutions: This issue typically stems from two primary causes. First, when running the ScanState and LoadState tools on modern Windows operating systems (Windows 7, Windows 8, or Windows 10), you must execute them in Administrator mode from an account with administrative credentials. Failure to do so means only the currently logged-on user’s profile will be included in the migration, omitting other user accounts on the system. To run in Administrator mode, navigate to Start > All Programs > Accessories, right-click Command Prompt, and select Run as administrator before specifying your USMT commands.

The second cause is that USMT will not migrate user accounts that have never been used on the computer. For example, if you create “User1” on a machine but “User1” never logs in, USMT will not include that account in the migration. This behavior is by design, as USMT only processes profiles that have been fully initialized by a user logon.

Unexpected Migration of Excluded Accounts¶

Problem: “User accounts that I excluded were migrated to the destination computer.”

Cause: This often occurs due to conflicting inclusion and exclusion options in your command. If a user is explicitly included using the /ui option while also being excluded with either the /ue or /uel options, the /ui (include) option takes precedence, resulting in the user’s migration. For instance, ScanState.exe /ui:domain1\* /ue:domain1\user1 would still migrate domain1\user1 because the inclusion rule overrides the exclusion.

Resolution: To prevent unintended migrations, review your command-line options carefully. For a comprehensive understanding of how to combine /ui and /ue options effectively, consult the examples provided in the USMT ScanState Syntax documentation. Proper use of these options is crucial for precise control over which user profiles are migrated.

Issues with the /uel Option¶

Problem: “I’m using the /uel option, but many accounts are still being included in the migration.”

Cause: The /uel option, which excludes users based on their last logon activity, relies on the last modified date of the user’s NTUser.dat file. However, there are scenarios where this file’s last modified date may not accurately reflect the user’s actual last sign-in date. Factors like system updates or background processes can sometimes alter this timestamp, leading to unintended inclusions.

Resolution: This behavior is a known limitation of the /uel option. If you encounter situations where /uel doesn’t exclude users as expected, you may need to manually exclude those specific users by utilizing the /ue option. This provides a more precise method for controlling which user profiles are migrated when timestamp inconsistencies arise.

LoadState Return Code 71 during Profile Restoration¶

Problem: “The LoadState tool reports an error as return code 71 and fails to restore a user profile during a migration test.”

Cause: This issue commonly arises during migration tests when the ScanState tool is run on a test computer, and then user profiles are subsequently deleted to test the LoadState tool on the same machine. This can leave a conflicting key in the registry, even if the user profile’s folders and files are removed. Using commands like net use to remove a user profile only deletes the associated files but does not clean up the corresponding registry key, leading to inconsistencies that hinder LoadState.

Resolution: To properly delete a user profile and avoid this conflict, always use the User Accounts item in the Control Panel. If an incomplete deletion has already occurred, you can correct it by:
1. Opening the Registry Editor by typing regedit.exe at an elevated command prompt.
2. Navigating to HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\ProfileList.
3. Locating the System Identifier (SID) key corresponding to the user profile you are attempting to remove. Each user profile is stored under a unique SID key within ProfileList.
4. Deleting the identified key. This ensures the registry is clean, allowing LoadState to restore the profile without conflict.

Files Encrypted After Migration¶

Problem: “Files that weren’t encrypted before the migration are now encrypted with the account used to run the LoadState tool.”

Cause: This problem occurs when the ScanState tool is executed with the /EFS:copyraw option to migrate encrypted files and Encrypting File System (EFS) certificates. If a folder’s encryption attribute was set, but its file contents were unencrypted prior to migration, the attribute might be incorrectly applied to the files by the account running LoadState. This results in previously unencrypted files becoming encrypted with the LoadState execution account’s EFS key.

Resolution: Before running the ScanState tool for any migration involving encrypted files and EFS certificates, it is crucial to review and adjust encryption settings on files and folders using the Cipher tool. This command-line utility allows you to ensure consistency. Specifically, you must either remove the encryption attribute from folders containing unencrypted files or ensure that all files within an encrypted folder are themselves encrypted. To fix files that have already been incorrectly migrated, sign into the computer with the account that was used to run the LoadState tool, and then manually remove the encryption from the affected files.

LoadState Return Code 71 with Windows Error 2202¶

Problem: “The LoadState tool reports an error as return code 71 and a Windows Error 2202 in the log file.”

Cause: This specific error code combination often indicates that the computer name was changed during an offline migration of a local user profile. When the original computer name is referenced in the profile’s data, and the destination name differs, LoadState can encounter conflicts when trying to restore the profile, leading to this error.

Resolution: To resolve this, use the /mu option when running the LoadState tool to specify a new name for the user’s profile, effectively mapping the old profile name to the new one. For example:

LoadState.exe /i:MigApp.xml /i:MigDocs.xml \\server\share\migration\mystore /progress:Progress.log /l:LoadState.log /mu:fareast\user1:farwest\user1

This command tells LoadState to migrate the user fareast\user1 and rename their profile to farwest\user1 on the destination machine, accommodating the computer name change.

Command-line Problems¶

Command-line issues are common and often relate to path lengths or logging permissions. Careful attention to syntax and environment is necessary to prevent these errors.

Excessive File Path Length¶

Problem: “I received the following error message: ‘Usage Error: You can’t specify a file path with any of the command-line options that exceeds 256 characters.’”

Cause: This error message can appear even if your specified store or file path seems short. The path length is calculated based on the absolute path from the root. For example, if you execute ScanState.exe /o store from C:\Program Files\USMT40, each character in C:\Program Files\USMT40 is added to the length of “store” to determine the total path length. If this combined length exceeds 256 characters, the error is triggered.

Resolution: Ensure that the total path length, encompassing both the current directory from which the command is executed and the specified store path, does not exceed 256 characters. This often requires running USMT commands from a shorter directory path or choosing a shorter path for the migration store itself.

Log File Creation Failure¶

Problem: “I received the following error message: ‘USMT was unable to create the log file(s). Ensure that you have write access to the log directory.’”

Cause: This error typically occurs when the ScanState or LoadState tools are run from a shared network resource without explicitly specifying a log file path. Without the /l option, USMT attempts to create log files in the current working directory, which, in the case of a network share, might lack the necessary write permissions for the user or system account executing the command.

Resolution: To resolve this issue in such scenarios, you must explicitly specify the log file path using the /l:ScanState.log or /l:LoadState.log option. For example, ScanState.exe \\server\share\migration\mystore /l:C:\USMTLogs\ScanState.log. This directs USMT to create the log file in a location where the executing account has guaranteed write access, such as a local drive or another designated share with appropriate permissions.

XML File Problems¶

USMT’s flexibility comes from its XML configuration files. Errors in these files, or misunderstandings of their generation, can lead to unexpected migration behavior.

Incomplete Config.xml File¶

Problem: “I used the /genconfig option to create a Config.xml file, but I see only a few applications and components that are in MigApp.xml. Why does Config.xml not contain all of the same applications?”

Cause: The Config.xml file generated using the /genconfig option only includes operating system components, applications, and user document sections that are explicitly defined in the provided .xml files and are currently installed on the computer at the time the command is run. If an application is listed in MigApp.xml but is not present on the machine when /genconfig is executed, it will not appear in the generated Config.xml file.

Resolution: To ensure that your Config.xml accurately reflects all desired applications and components, install all relevant applications on the computer before running the /genconfig option. Then, execute ScanState.exe with all the necessary .xml files, including MigApp.xml and MigDocs.xml, to generate a comprehensive Config.xml. For instance, use the command:

ScanState.exe /genconfig:Config.xml /i:MigDocs.xml /i:MigApp.xml /v:5 /l:ScanState.log

This process guarantees that Config.xml will contain all the applications and components that USMT recognizes as present and configurable for migration.

Validating Custom XML File Syntax¶

Problem: “I’m having problems with a custom .xml file that I authored, and I can’t verify that the syntax is correct.”

Resolution: The USMT distribution includes the XML schema file MigXML.xsd, which is crucial for validating the syntax of your custom migration .xml files. You can load MigXML.xsd into any XML authoring tool that supports schema validation. Once the schema is loaded, open your custom .xml file within the same tool. The authoring tool will then highlight any syntax errors or deviations from the schema, guiding you to correct them. For detailed examples and information on using various XML elements within USMT, refer to the USMT XML Reference documentation. This resource provides a comprehensive guide to USMT’s XML structure and capabilities.

Troubleshooting MigXML Helper Functions¶

Problem: “I’m using a MigXML helper function, but the migration isn’t working the way I expected it to. How do I troubleshoot this issue?”

Cause: This issue typically arises from incorrect syntax or improper implementation of a MigXML helper function within your .xml files. While USMT might return a “Success” code, the actual collection or application of files may not align with your expectations. The helper function might be misinterpreting rules or failing to execute as intended due to a subtle error in its definition or parameters.

Resolution: To diagnose problems with MigXML helper functions, thoroughly examine the ScanState or LoadState log files. Search for the component name that contains the MigXML helper function, or directly for the helper function’s title. The logs often contain specific warning messages related to the helper function’s execution, indicating why it failed to perform as expected. These warnings are crucial for identifying and correcting the incorrect syntax or logic within your .xml file.

Migration Problems¶

Even with correct configurations, specific migration scenarios can pose unique challenges. Understanding how USMT handles conflicting rules, specific data types, and system features is essential for successful data transfer.

Excluded Files Still Migrating¶

Problem: “Files that I specified to exclude are still being migrated.”

Cause: The most common reason for this issue is the presence of another rule that explicitly includes the files you intended to exclude. USMT employs a complex set of rules for conflict resolution and precedence. If a more specific inclusion rule or a conflicting rule exists, it will override a general exclusion rule, leading to the unexpected migration of the files.

Resolution: To diagnose and resolve this, carefully review all your migration .xml files for any conflicting rules. Pay close attention to the order of operations and specificity of your inclusion and exclusion patterns. For a detailed understanding of how USMT resolves conflicts and applies precedence, consult the “Conflicts and Precedence” section in the official documentation. Additionally, the Diagnostic Log section within the “Log Files” article can provide granular information about which rules were applied to specific files, helping you identify the overriding inclusion rule.

Incorrect Folder Rerouting¶

Problem: “I specified rules to move a folder to a specific location on the destination computer, but it hasn’t migrated correctly.”

Cause: This problem typically indicates an error in the XML syntax of your folder rerouting rules. Even minor typos or incorrect nesting of elements within the .xml file can cause USMT to misinterpret your instructions, leading to the folder not being moved or being placed in an unintended location.

Resolution: Use the USMT XML schema (MigXML.xsd) with an XML authoring tool to write and validate your migration .xml files. The schema will highlight any syntax errors, making it easier to identify and correct issues. Furthermore, review the XML examples provided in the following official documentation articles:
* “Conflicts and precedence”
* “Exclude files and settings”
* “Reroute files and settings”
* “Include files and settings”
* “Custom XML examples”
These examples demonstrate correct syntax and best practices for various migration scenarios, including folder rerouting.

Desktop Background Not Appearing¶

Problem: “After LoadState completes, the new desktop background doesn’t appear on the destination computer.”

Cause: There are three typical causes for this. The primary reason is that certain user interface settings, such as fonts, desktop backgrounds, and screen-saver configurations, are not immediately applied by LoadState. These settings only take effect after the destination computer has been restarted or the user logs out and then back in.

Resolution: To fix this issue, simply instruct the end-user to sign out of their account and then log back on. Upon re-login, the migrated desktop background and other cached UI settings should correctly appear, reflecting the changes from the migration.

Incomplete PST File Migration¶

Problem: “I included MigApp.xml in the migration, but some PST files aren’t migrating.”

Cause: The default MigApp.xml file is designed to migrate only PST files that are actively linked to existing Microsoft Outlook profiles. If a PST file exists on the source machine but is not currently associated with an Outlook profile, MigApp.xml will not automatically include it in the migration. This is a common scenario for archived or unlinked PST files.

Resolution: To ensure that all necessary PST files, including those not linked to Outlook profiles, are migrated, you must create a separate, custom migration rule. This custom rule should explicitly define the paths to any unlinked PST files you wish to capture, using the appropriate XML elements within a custom .xml file. This allows for comprehensive PST file migration beyond the scope of the default MigApp.xml functionality.

USMT Does Not Migrate the Start Layout¶

Problem: “You’re using USMT to migrate profiles from one installation of Windows 10 to another installation of Windows 10 on different hardware. After migration, the user signs in on the new device and doesn’t have the Start menu layout they had previously configured.”

Cause: This issue stems from a significant code change in the Windows 10 Start Menu, specifically from version 1607 (Anniversary Update) and later. These changes introduced an incompatibility with USMT’s traditional methods for migrating the Start layout, rendering the built-in functionality ineffective for this specific component.

Resolution: A viable workaround involves manually exporting and importing the Start layout using Windows PowerShell commands.
1. Export Layout: With the user signed in on the source machine, back up their Start layout using the following Windows PowerShell command. You can specify an alternative path if desired:

Export-StartLayout -Path "C:\Layout\user1.xml"

This command saves the current Start Menu configuration to an XML file.
2. Migrate Profile: Proceed with migrating the user’s profile using USMT as usual. The Start layout data will not be handled by USMT itself.
3. Import Layout: Before the user signs in on the new device, import the saved Start layout using this Windows PowerShell command:

Import-StartLayout -LayoutPath "C:\Layout\user1.xml" -MountPath %systemdrive%

This command applies the exported layout to the specified mount path, which represents the user’s profile on the new device.

It’s important to note that this workaround modifies the Default user’s Start layout on the destination device. While effective for single-user scenarios, it does not scale well for mass migrations or multi-user devices. If other users will sign on to the device, you should delete layoutmodification.xml from the Default user profile after the initial user’s layout has been imported. Otherwise, all subsequent users logging into that device will inherit the imported Start layout, which might not be desirable.

Offline Migration Problems¶

Offline migrations, performed when the source operating system is not running, offer unique advantages but also present a distinct set of challenges.

Limited System Setting Migration in Offline Mode¶

Problem: “Some of my system settings don’t migrate in an offline migration.”

Cause: Not all system settings are supported for migration in an offline scenario. Certain configurations, such as desktop backgrounds, network printers, and some device-specific settings, rely on a running operating system environment or active network connections to be properly identified and migrated. For a comprehensive list of what USMT migrates and what it does not, particularly in offline contexts, refer to the “What does USMT migrate?” documentation.

Resolution: In an offline migration, any system settings that are not supported by USMT must be restored manually on the destination computer. This often involves reconfiguring network printer connections, setting desktop backgrounds, and adjusting other environment-specific settings post-migration.

ScanState Failure with Return Code 26¶

Problem: “The ScanState tool fails with return code 26.”

Cause: A common cause for return code 26 during offline migration is an active temporary profile on the source computer. This temporary profile typically maps to c:\users\temp. The ScanState log often contains a MigStartupOfflineCaught exception message, specifically indicating a “User profile duplicate SID error.” This suggests that USMT is encountering an unexpected or corrupted temporary profile during its scan.

Resolution: You have two primary options to resolve this. The simplest is to reboot the computer. A reboot often resolves temporary profile issues by clearing the current session and allowing the system to initialize profiles correctly. Alternatively, you can set the environment variable MIG_FAIL_ON_PROFILE_ERROR=0. This tells USMT to skip the error and exclude the problematic temporary profile from the migration, allowing the ScanState operation to complete.

Inconsistent Include/Exclude Rules for Offline User Profiles¶

Problem: “Include and Exclude rules for migrating user profiles don’t work the same offline as they do online.”

Cause: When performing an offline migration, the DNS server cannot be queried to resolve user names to their Security Identifiers (SIDs), or vice versa. This means that rules relying on user names (e.g., /ui:domain\user) may not function as expected, as USMT cannot dynamically translate the name to a SID in an offline context.

Resolution: When running the ScanState tool in an offline scenario, always use the Security Identifier (SID) to include or exclude a user, rather than their user name. For example:

ScanState.exe /ui:S1-5-21-124525095-708259637-1543119021*

The wildcard (*) at the end of the SID (e.g., S1-5-21-124525095-708259637-1543119021*) is crucial. It ensures that the SID_Classes key, which contains user-specific class registrations, is also migrated. You can also use patterns for SIDs to identify generic users or groups. For example, /ue:*-500 can be used to exclude local administrator accounts. For more information on Windows SIDs and their structure, consult the “Security identifiers” documentation.

Disk Wipe Script Fails on 64-bit System After ScanState¶

Problem: “My script to wipe the disk fails after running the ScanState tool on a 64-bit system.”

Cause: This issue typically occurs because the HKLM (HKEY_LOCAL_MACHINE) registry hive is not properly unloaded after the ScanState tool has finished running. On 64-bit systems, USMT might leave certain registry hives loaded, which can prevent disk wiping utilities or scripts from accessing or deleting files associated with those hives.

Resolution: To resolve this, you can either reboot the computer after the ScanState tool completes or manually unload the specific registry hive from the command prompt. For example, at an elevated command prompt, enter:

reg.exe unload hklm\$dest$software

This command explicitly unloads the $dest$software hive from HKLM, freeing up the resources and allowing subsequent disk wiping operations to proceed without interference.

Hard-Link Migration Problems¶

Hard-link migrations are efficient for same-machine refreshes, but they have specific limitations, especially concerning encrypted files and store deletion.

EFS Files Not Restored to New Partition¶

Problem: “EFS files aren’t restored to the new partition.”

Cause: Encrypting File System (EFS) files cannot be moved to a new partition using a hard link. The /efs:hardlink command-line option is designed exclusively for files migrated on the same partition. When you attempt to migrate EFS files across partitions with this option, the hard links cannot be created correctly, resulting in the EFS files not being transferred to the new partition.

Resolution: To successfully migrate EFS files to a new partition, you must use the /efs:copyraw command-line option. This option instructs USMT to copy the EFS files and their associated certificates in their raw, encrypted state during the migration, rather than attempting to create hard links. Alternatively, you can manually copy the EFS files from the hard-link store to the new partition after the migration, though this is a less automated approach.

ScanState Cannot Delete Previous Hard-Link Migration Store¶

Problem: “The ScanState tool can’t delete a previous hard-link migration store.”

Cause: This issue arises when the migration store contains hard links to files that are currently locked by the operating system or other running processes. USMT cannot delete a hard-link store if any of its linked files are in use, as this would compromise the integrity of the active file system.

Resolution: To resolve this, you can use the UsmtUtils tool to delete the locked store or simply change the store’s name. For example, at a command prompt, enter:

UsmtUtils.exe /rd <storedir>

This command forces the removal of the specified directory, including any persistent hard links. Additionally, rebooting the machine is often an effective solution, as it releases all file locks and allows for the successful deletion of the old hard-link migration store.

Data Collection for Support¶

If you encounter persistent issues that you are unable to resolve with the provided troubleshooting steps, and you require assistance from Microsoft support, it is highly recommended to gather comprehensive diagnostic information beforehand. Utilizing the procedures outlined in the “Gather information by using TSS for deployment-related issues” guide will ensure you collect all necessary data points, facilitating a quicker and more efficient resolution process with support engineers.

We hope this expanded troubleshooting guide assists you in resolving common USMT migration issues. Should you have further questions or encounter new challenges, please feel free to comment below or share your experiences. Your insights help improve the USMT community’s knowledge base.