SetupDiag

About SetupDiag

SetupDiag is a diagnostic tool that can be used to obtain details about why a Windows upgrade was unsuccessful.

SetupDiag works by examining Windows Setup log files. It attempts to parse these log files to determine the root cause of a failure to update or upgrade the computer to Windows. SetupDiag can be run on the computer that failed to update. The logs can also be exported from the computer to another location and then running SetupDiag in offline mode.

SetupDiag is included with Windows Setup in all currently supported versions of Windows.

During the upgrade process, Windows Setup extracts all its sources files, including SetupDiag.exe, to the %SystemDrive%$Windows.~bt\Sources directory. If there's an issue with the upgrade, SetupDiag automatically runs to determine the cause of the failure.

When run by Windows Setup, the following parameters are used:

• /ZipLogs:False
• /Format:xml
• /Output:%windir%\logs\SetupDiag\SetupDiagResults.xml
• /RegPath:HKEY_LOCAL_MACHINE\SYSTEM\Setup\SetupDiag\Results

The resulting SetupDiag analysis can be found at %WinDir%\Logs\SetupDiag\SetupDiagResults.xml and in the registry under HKLM\SYSTEM\Setup\SetupDiag\Results.

If the upgrade process proceeds normally, the Sources directory including SetupDiag.exe is moved under %SystemDrive%\Windows.Old for cleanup. If the Windows.old directory is deleted later, SetupDiag.exe is also removed.

Requirements

1. The destination version of Windows must be a currently supported version of Windows. The originally installed version of Windows can be a version of Windows that's out of support as long as:

   • The destination version of Windows is a currently supported version of Windows.
   • Upgrade to the destination version of Windows is supported from the original installed version of Windows.

2. .NET Framework 4.7.2 or newer must be installed. To determine which version of .NET is preinstalled with a specific version of Windows, see .NET Framework system requirements: Supported client operating systems. To determine which version of .NET is currently installed, see How to: Determine Which .NET Framework Versions Are Installed.

   The following command-line query can be used to display the currently installed version of .NET:

   reg.exe query "HKLM\SOFTWARE\Microsoft\Net Framework Setup\NDP\v4" /s
   

   As long as at least the required version of .NET is installed, no additional action is required, including if a newer version is installed.

Using SetupDiag

To quickly use SetupDiag on the current computer:

1. Verify that the system meets the requirements.

2. Download SetupDiag.

3. If the web browser asks what to do with the file, choose Save. By default, the file is saved to the Downloads folder. If desired, the file can also be saved to a different location by using Save As.

4. When SetupDiag finishes downloading, open the folder where the file was downloaded. By default, this folder is the Downloads folder, which is displayed in File Explorer under Quick access in the left navigation pane.

5. Double-click the SetupDiag file to run it. Select Yes if asked to approve running the program.

Double-clicking the file to run it automatically closes the command window when SetupDiag completes its analysis. To instead keep the window open to review the messages SetupDiag generates, run the program by typing SetupDiag at the command prompt instead of double-clicking it. When running from a command prompt, make sure to change directories to where SetupDiag is located.

1. A command window opens while SetupDiag diagnoses the computer. Wait for this process to finish.

2. When SetupDiag finishes, two files are created in the same folder where SetupDiag was run from. One is a configuration file, the other is a log file.

3. Use Notepad to open the log file SetupDiagResults.log.

4. Review the information that is displayed. If a rule was matched, this information can say why the computer failed to upgrade, and potentially how to fix the problem. See the section Text log sample.

For instructions on how to run the tool in offline mode and with more advanced options, see the sections Parameters and Examples.

Parameters

Examples

• In the following example, SetupDiag is run with default parameters in online mode. The results file is SetupDiagResults.log in the same folder where SetupDiag is run.

  SetupDiag.exe
  

• In the following example, SetupDiag is run in online mode (this mode is the default). It knows where to look for logs on the current (failing) system, so there's no need to gather logs ahead of time. A custom location for results is specified.

  SetupDiag.exe /Output:C:\SetupDiag\Results.log
  

• The following example uses the /Output parameter to save results to a path name that contains a space:

  SetupDiag /Output:"C:\Tools\SetupDiag\SetupDiag Results\Results.log"
  

• The following example specifies that SetupDiag is to run in offline mode, and to process the log files found in D:\Temp\Logs\LogSet1.

  SetupDiag.exe /Output:C:\SetupDiag\Results.log /LogsPath:D:\Temp\Logs\LogSet1
  

• The following example sets recovery scenario in offline mode. In the example, SetupDiag searches for reset/recovery logs in the specified LogsPath location and output the results to the directory specified by the /Output parameter.

  SetupDiag.exe /Output:C:\SetupDiag\RecoveryResults.log /LogsPath:D:\Temp\Cabs\PBR_Log /Scenario:Recovery
  

• The following example sets recovery scenario in online mode. In the example, SetupDiag searches for reset/recovery logs on the current system and output results in XML format.

  SetupDiag.exe /Scenario:Recovery /Format:xml
  

• The following example is an example of Offline Mode. SetupDiag is instructed to parse setup/upgrade log files in the LogsPath directory and output the results to C:\SetupDiag\Results.txt.

  SetupDiag.exe /Output:C:\SetupDiag\Results.txt /LogsPath:D:\Temp\Logs\Logs1 /RegPath:HKEY_CURRENT_USER\SYSTEM\SetupDiag
  

• The following example is an example of Online Mode. SetupDiag is instructed to look for setup/upgrade logs on the current system and output its results in XML format to C:\SetupDiag\Results.xml.

  SetupDiag.exe /Output:C:\SetupDiag\Results.xml /Format:xml
  

• The following example is an example of Online Mode where no parameters are needed or used. SetupDiag is instructed to look for setup/upgrade logs on the current system and output the results to the same directory where SetupDiag is located.

  SetupDiag.exe
  

• The following example is an example of Reset/Recovery Offline Mode. SetupDiag is instructed to look for reset/recovery logs in the specified LogsPath location. It then outputs the results to the directory specified by the /Output parameter.

  SetupDiag.exe /Output:C:\SetupDiag\RecoveryResults.log /LogsPath:D:\Temp\Cabs\PBR_Log /Scenario:Recovery
  

• The following example is an example of Reset/Recovery Online Mode. SetupDiag is instructed to look for reset/recovery logs on the current system and output its results in XML format.

  SetupDiag.exe /Scenario:Recovery /Format:xml
  

Log files

Windows Setup Log Files and Event Logs has information about where logs are created during Windows Setup. For offline processing, SetupDiag should be run against the contents of the entire folder. For example, depending on when the upgrade failed, copy one of the following folders to the offline location:

• \$Windows.~bt\sources\panther
• \$Windows.~bt\Sources\Rollback
• \Windows\Panther
• \Windows\Panther\NewOS

If the parent folder and all subfolders are copied, SetupDiag automatically searches for log files in all subdirectories.

Setup bug check analysis

When Microsoft Windows encounters a condition that compromises safe system operation, the system halts. This condition is called a bug check. This condition is also commonly referred to as a system crash, a kernel error, a Stop error, or BSOD. Typically a hardware device, hardware driver, or related software causes this error.

If crash dumps are enabled on the system, a crash dump file is created. If the bug check occurs during an upgrade, Windows Setup extracts a minidump (setupmem.dmp) file. SetupDiag can also debug these setup-related minidumps.

To debug a setup-related bug check:

• Specify the /LogsPath parameter. Memory dumps can't be debugged in online mode.

• Gather the setup memory dump file (`setupmem.dmp) from the failing system.

  Setupmem.dmp is created in either %SystemDrive%$Windows.~bt\Sources\Rollback, or in %WinDir%\Panther\NewOS\Rollback depending on when the bug check occurs.

• Install the Windows Debugging Tools on the computer that runs SetupDiag.

In the following example, the setupmem.dmp file is copied to the D:\Dump directory and the Windows Debugging Tools are installed prior to running SetupDiag:

SetupDiag.exe /Output:C:\SetupDiag\Dumpdebug.log /LogsPath:D:\Dump

Known issues

• Some rules can take a long time to process if the log files involved are large.

Sample output

The following command is an example where SetupDiag is run in offline mode.

D:\SetupDiag>SetupDiag.exe /output:c:\setupdiag\result.xml /logspath:D:\Tests\Logs\f55be736-beed-4b9b-aedf-c133536c946e /format:xml

SetupDiag v1.7.0.0
Copyright (c) Microsoft Corporation. All rights reserved.

Searching for setup logs...
Found d:\tests\Logs\f55be736-beed-4b9b-aedf-c133536c946e\setupact_6.log with update date 6/12/2023 2:44:20 PM to be the correct setup log.
Found d:\tests\Logs\f55be736-beed-4b9b-aedf-c133536c946e\setupact_1.log with update date 6/12/2023 2:45:19 PM to be the correct rollback log.

Gathering baseline information from setup logs...

SetupDiag: processing rule: CompatScanOnly.
...No match.

...

SetupDiag: processing rule: DISMImageSessionFailure.
..
Error: SetupDiag reports DISM provider failure.
Last Phase: Safe OS
Last Operation: Apply Optional Component status
Message = Failed to get the IDismImage instance from the image session
Function: CDISMManager::CloseImageSession
Error: 0x800706ba
Recommend you re-download the update source files, reboot and try the update again.

SetupDiag found 1 matching issue.

SetupDiag results were logged to: c:\setupdiag\results.xml
Logs ZipFile created at: c:\setupdiag\Logs_14.zip

Rules

When SetupDiag searches log files, it uses a set of rules to match known issues. These rules are contained in an xml file. The xml file might be updated with new and updated rules as new versions of SetupDiag are made available.

Each rule name and its associated unique rule identifier are listed with a description of the known upgrade-blocking issue. In the rule descriptions, the term down-level refers to the first phase of the upgrade process, which runs under the original OS.

Sample logs

Text log sample

Matching Profile found: OptionalComponentOpenPackageFailed - 22952520-EC89-4FBD-94E0-B67DF88347F6
System Information:
    Machine Name = Offline
    Manufacturer = MSI
    Model = MS-7998
    HostOSArchitecture = x64
    FirmwareType = PCAT
    BiosReleaseDate = 20160727000000.000000+000
    BiosVendor = BIOS Date: 07/27/16 10:01:46 Ver: V1.70
    BiosVersion = 1.70
    HostOSVersion = 10.0.15063
    HostOSBuildString = 15063.0.amd64fre.rs2_release.170317-1834
    TargetOSBuildString = 10.0.16299.15 (rs3_release.170928-1534)
    HostOSLanguageId = 2057
    HostOSEdition = Core
    RegisteredAV = Windows Defender,
    FilterDrivers = WdFilter,wcifs,WIMMount,luafv,Wof,FileInfo,
    UpgradeStartTime = 3/21/2023 9:47:16 PM
    UpgradeEndTime = 3/21/2023 10:02:40 PM
    UpgradeElapsedTime = 00:15:24
    ReportId = dd4db176-4e3f-4451-aef6-22cf46de8bde

Error: SetupDiag reports Optional Component installation failed to open OC Package. Package Name: Foundation, Error: 0x8007001F
Recommend you check the "Windows Modules Installer" service (Trusted Installer) is started on the system and set to automatic start, reboot and try the update again.  Optionally, you can check the status of optional components on the system (search for Windows Features), uninstall any unneeded optional components, reboot and try the update again.
Error: SetupDiag reports down-level failure, Operation: Finalize, Error: 0x8007001F - 0x50015
Refer to https://zcusa.951200.xyz/windows/deployment/upgrade/upgrade-error-codes for error information.

XML log sample

<?xml version="1.0" encoding="utf-16"?>
<SetupDiag xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="https://zcusa.951200.xyz/windows/deployment/upgrade/setupdiag">
  <Version>1.7.0.0</Version>
  <ProfileName>FindSPFatalError</ProfileName>
  <ProfileGuid>A4028172-1B09-48F8-AD3B-86CDD7D55852</ProfileGuid>
  <SystemInfo>
    <MachineName>Offline</MachineName>
    <Manufacturer>Gigabyte Technology Co., Ltd.</Manufacturer>
    <Model>X470 AORUS ULTRA GAMING</Model>
    <HostOSArchitecture>1033</HostOSArchitecture>
    <FirmwareType>UEFI</FirmwareType>
    <BiosReleaseDate>20180808000000.000000+000</BiosReleaseDate>
    <BiosVendor>F3</BiosVendor>
    <BiosVersion />
    <HostOSVersion>10.0.18908</HostOSVersion>
    <HostOSBuildString>18908.1000.amd64fre.rs_prerelease.190524-1658</HostOSBuildString>
    <TargetOSBuildString>10.0.18912.1001 (rs_prerelease.190601-1739)</TargetOSBuildString>
    <HostOSLanguageId />
    <HostOSEdition>Professional</HostOSEdition>
    <RegisteredAV>Windows Defender</RegisteredAV>
    <FilterDrivers />
    <UpgradeStartTime>2023-06-06T21:19:10</UpgradeStartTime>
    <UpgradeElapsedTime />
    <UpgradeEndTime>2023-06-06T22:21:49</UpgradeEndTime>
    <RollbackStartTime>0001-01-01T00:00:00</RollbackStartTime>
    <RollbackEndTime>0001-01-01T00:00:00</RollbackEndTime>
    <RollbackElapsedTime />
    <FinalizeStartTime>0001-01-01T00:00:00</FinalizeStartTime>
    <PostOOBESuccessTime>0001-01-01T00:00:00</PostOOBESuccessTime>
    <TotalOfflineTime />
    <CommercialId>Offline</CommercialId>
    <CV>MgUweCZk90KdwUiZ</CV>
    <SetupReportId>F21F8FB6-00FD-4349-84FB-2AC75F389E73</SetupReportId>
    <ReportId>F21F8FB6-00FD-4349-84FB-2AC75F389E73</ReportId>
  </SystemInfo>
  <LogErrorLine>2023-06-06 21:47:11, Error                 SP     Error converting install time 5/2/2023 to structure[gle=0x00000057]</LogErrorLine>
  <FailureData>
Error: SetupDiag reports Fatal Error.
Last Setup Phase = Downlevel
Last Setup Operation: Gather data, scope: EVERYTHING
Error: 0x00000057</FailureData>
  <FailureData>LogEntry: 2023-06-06 21:47:11, Error                 SP     Error converting install time 5/2/2023 to structure[gle=0x00000057]</FailureData>
  <FailureData>LogEntry: 2023-06-06 21:47:11, Error                 SP     Error converting install time 5/2/2023 to structure[gle=0x00000057]</FailureData>
  <FailureData>
Refer to "https://zcusa.951200.xyz/windows/desktop/Debug/system-error-codes" for error information.</FailureData>
  <FailureDetails>Err = 0x00000057, LastOperation = Gather data, scope: EVERYTHING, LastPhase = Downlevel</FailureDetails>
</SetupDiag>

JSON log sample

{
    "Version":"1.6.0.0",
    "ProfileName":"FindSPFatalError",
    "ProfileGuid":"A4028172-1B09-48F8-AD3B-86CDD7D55852",
    "SystemInfo":{
        "BiosReleaseDate":"20180808000000.000000+000",
        "BiosVendor":"F3",
        "BiosVersion":"F3",
        "CV":"MgUweCZk90KdwUiZ",
        "CommercialId":"Offline",
        "FilterDrivers":"",
        "FinalizeStartTime":"\/Date(-62135568000000-0800)\/",
        "FirmwareType":"UEFI",
        "HostOSArchitecture":"x64",
        "HostOSBuildString":"18908.1000.amd64fre.rs_prerelease.190524-1658",
        "HostOSEdition":"Professional",
        "HostOSLanguageId":"",
        "HostOSVersion":"",
        "MachineName":"Offline",
        "Manufacturer":"Gigabyte Technology Co., Ltd.",
        "Model":"X470 AORUS ULTRA GAMING",
        "PostOOBESuccessTime":"\/Date(-62135568000000-0800)\/",
        "RegisteredAV":"Windows Defender",
        "ReportId":"F21F8FB6-00FD-4349-84FB-2AC75F389E73",
        "RollbackElapsedTime":"PT0S",
        "RollbackEndTime":"\/Date(-62135568000000-0800)\/",
        "RollbackStartTime":"\/Date(-62135568000000-0800)\/",
        "SetupReportId":"F21F8FB6-00FD-4349-84FB-2AC75F389E73",
        "TargetOSArchitecture":null,
        "TargetOSBuildString":"10.0.18912.1001 (rs_prerelease.190601-1739)",
        "TotalOfflineTime":"PT0S",
        "UpgradeElapsedTime":"PT1H2M39S",
        "UpgradeEndTime":"\/Date(1559884909000-0700)\/",
        "UpgradeStartTime":"\/Date(1559881150000-0700)\/"
    },
    "LogErrorLine":"2023-06-06 21:47:11, Error                 SP     Error converting install time 5\/2\/2023 to structure[
        gle=0x00000057
    ]",
    "FailureData":[
        "\u000aError: SetupDiag reports Fatal Error.\u000aLast Setup Phase = Downlevel\u000aLast Setup Operation: Gather data, scope: EVERYTHING\u000aError: 0x00000057",
        "LogEntry: 2023-06-06 21:47:11, Error                 SP     Error converting install time 5\/2\/2023 to structure[
            gle=0x00000057
        ]",
        "LogEntry: 2023-06-06 21:47:11, Error                 SP     Error converting install time 5\/2\/2023 to structure[
            gle=0x00000057
        ]",
        "\u000aRefer to \"https:\/\/zcusa.951200.xyz\/windows\/desktop\/Debug\/system-error-codes\" for error information."
    ],
    "FailureDetails":"Err = 0x00000057, LastOperation = Gather data, scope: EVERYTHING, LastPhase = Downlevel",
    "DeviceDriverInfo":null,
    "Remediation":[
        
    ],
    "SetupPhaseInfo":null,
    "SetupOperationInfo":null
}

Example registry key

Related articles

• Resolve Windows upgrade errors: Technical information for IT Pros.