SetupDiag: How to Download and Use Microsoft's Windows Upgrade Diagnostic Tool
SetupDiag is a free Microsoft command line tool that reads Windows Setup log files and tells you why a Windows 10 or Windows 11 upgrade or feature update failed. Download SetupDiag.exe from Microsoft's official link, open an elevated Command Prompt in the download folder and run setupdiag.exe. It writes the cause it found, plus a recommended fix, to SetupDiagResults.log in the same folder.
This guide covers the official download, the requirements, the copy of SetupDiag that Windows already places on your PC, every command line parameter, and how to read and act on the results.
SetupDiag download: the official Microsoft link
SetupDiag is distributed by Microsoft only, through the download link on its SetupDiag documentation page. The link (go.microsoft.com/fwlink/?linkid=870142) always points to the current release, which matters because Microsoft recommends running the latest version: the detection rules ship inside the program and grow with each release.
SetupDiag is a single portable file, SetupDiag.exe. There is no installer, so nothing changes on the system until you run it. Save it to a folder you can find easily, for example C:\SetupDiag, because the tool writes its results and a zip archive of the parsed logs into the folder it runs from.
Avoid third-party download portals for this tool. Microsoft's link is free, needs no account, and guarantees you get the current rule set rather than an outdated mirror copy.
Requirements before you run it:
- Windows 10 or Windows 11. The target version of the upgrade must be a supported Windows release.
- Microsoft .NET Framework 4.7.2 or newer. Check with: reg.exe query "HKLM\SOFTWARE\Microsoft\Net Framework Setup\NDP\v4" /s
- An elevated Command Prompt (Run as administrator). Microsoft states the tool should be run elevated to work properly.
If .NET is missing or too old, our guide to the .NET Framework 4.8 offline installer shows where to get it from Microsoft.
SetupDiag on Windows 11 and Windows 10: it may already be on your PC
SetupDiag is included with Windows Setup in all currently supported versions of Windows, so you often do not need to download it at all. During an upgrade, Windows Setup extracts its source files, SetupDiag.exe included, to %SystemDrive%\$Windows.~bt\Sources. If the upgrade fails, SetupDiag runs automatically to determine the cause.
That automatic run leaves its analysis in two places:
- File: %WinDir%\Logs\SetupDiag\SetupDiagResults.xml
- Registry: HKLM\SYSTEM\Setup\SetupDiag\Results
Check these first after a failed feature update. If the XML file exists, you already have SetupDiag's verdict without running anything.
If the upgrade succeeds, the Sources folder (and SetupDiag.exe with it) moves to %SystemDrive%\Windows.old for cleanup, and it disappears when Windows.old is deleted. On a PC that rolled back long ago, or after Disk Cleanup removed the old installation files, the official download is the reliable way to get the tool.
The $Windows.~bt folder is hidden. Enable hidden items in File Explorer, or type the path directly into the address bar.
How to use SetupDiag: run it in online mode
Online mode is the default: SetupDiag searches the current PC for Windows Setup logs and analyzes them in one pass. Use it on the computer whose upgrade failed.
- Download SetupDiag.exe from Microsoft and save it to a folder such as C:\SetupDiag.
- Open Start, type cmd, right-click Command Prompt and select Run as administrator.
- Change to the folder: cd C:\SetupDiag
- Run: setupdiag.exe
- Wait until the console reports how many matching issues it found and where the results were logged.
- Open SetupDiagResults.log in the same folder with Notepad and read the matching rule and its recommendation.
SetupDiag scans these folders, which hold the logs from the different phases of an upgrade:
- \$Windows.~bt\Sources\Panther
- \$Windows.~bt\Sources\Rollback
- \Windows\Panther
- \Windows\Panther\NewOS
Our list of Windows upgrade log files explains what each of these folders contains. In online mode, SetupDiag also writes its results to the registry under HKLM\SYSTEM\Setup\MoSetup\Volatile\SetupDiag, which is useful when you collect results from several machines with a script.
Large log sets can take a while: Microsoft notes that some rules are slow to process when the logs are big. Let the scan finish rather than closing the window.
SetupDiag command line parameters
SetupDiag runs with no parameters, but the switches below control where results go, what format they use and which logs are parsed. All of them come from Microsoft's documentation.
| Parameter | What it does |
|---|---|
| /Output:"path\file" | Sets the results file. Default is SetupDiagResults.log in the run folder. Quote paths with spaces; UNC paths work. |
| /LogsPath:folder | Offline mode: parses logs in that folder and all its subfolders. |
| /ZipLogs:True or False | Creates a zip of the results and parsed logs. Default is True. |
| /Format:xml or json | Changes the output format. Default is plain text. |
| /Scenario:Recovery or Debug | Recovery parses reset and recovery logs instead of upgrade logs; Debug analyzes memory dumps when the debugging tools are installed. |
| /Verbose | Writes an extra diagnostic log with debug details. |
| /NoTel | Stops SetupDiag from sending telemetry to Microsoft. |
| /RegPath:key | Sets a custom registry path for results (must start with HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER). |
| /AddReg | Writes results to the registry in offline mode (online mode does this by default). |
| /? | Shows the built-in help. |
The old /Mode:Offline switch from early versions is deprecated: specifying /LogsPath switches to offline mode automatically. Two practical combinations: setupdiag.exe /Output:C:\SetupDiag\Results.xml /Format:xml for machine-readable results, and setupdiag.exe /Scenario:Recovery when a Reset this PC operation failed rather than an upgrade.
Offline mode: analyze logs from another PC
Offline mode lets SetupDiag analyze Windows Setup logs that were copied from another computer, which is the way to go when the failing PC is slow, locked down or managed remotely. Point /LogsPath at the folder holding the copied logs.
- On the failing PC, copy the complete Panther, Rollback or NewOS folder that matches the phase where the upgrade stopped, including all subfolders.
- Place the copy on the analysis PC, for example in D:\Temp\Logs\LogSet1.
- In an elevated Command Prompt, run: setupdiag.exe /Output:C:\SetupDiag\Results.log /LogsPath:D:\Temp\Logs\LogSet1
SetupDiag searches the folder recursively, so copying a parent folder includes every log beneath it.
SetupDiag can also debug the setupmem.dmp memory dump that Windows Setup sometimes writes when an upgrade crashes. The dump sits in %SystemDrive%\$Windows.~bt\Sources\Rollback or %WinDir%\Panther\NewOS\Rollback. Install the Windows Debugging Tools first, copy the dump to a folder, then run setupdiag.exe /Output:C:\SetupDiag\Dumpdebug.log /LogsPath:D:\Dump. Dump analysis works in offline mode only.
Reading SetupDiag results and fixing common failures
SetupDiag reports the rule that matched, the failure details (often a hex error code) and, for many rules, a recommended fix. A typical entry starts with "Matching Profile found:" followed by the rule name and its GUID. The rule set covers 64 failure patterns in the current documentation, and each rule has a name you can search in Microsoft's rule table for a description.
| Rule name | Meaning | What to check |
|---|---|---|
| DiskSpaceFailure | The system drive ran out of space after the first reboot into the upgrade. | Free space on C:, then retry. |
| BitLockerHardblock | BitLocker is on, but the target edition does not support it. | The edition you are upgrading to. |
| DuplicateUserProfileFailure | One user profile is linked to several SIDs. | Remove the stale profile entry. |
| OptionalComponentOpenPackageFailed | Setup could not open an optional component package. | Windows Modules Installer service set to automatic, reboot, retry (Microsoft's own recommendation). |
| CompatScanOnly | Setup ran a compatibility scan only. | Not a failure: no upgrade was attempted. |
SetupDiag only recognizes failures that are defined in its rules. When it reports no matching issue, the cause is new or unusual, and the logs need a manual look: our guide on how to analyze Windows upgrade errors walks through that process. Once the cause is fixed, retry the upgrade with a clean installer such as the Windows 11 Installation Assistant.
FAQ
Is SetupDiag safe to run?
Yes, when you get it from Microsoft's official link. It reads log files, writes a results file, a zip archive and registry results, and does not change your Windows installation.
Does SetupDiag fix the upgrade problem itself?
No. SetupDiag diagnoses only: it names the cause and often recommends a fix, but you apply the fix and retry the upgrade yourself.
Can I stop SetupDiag from sending data to Microsoft?
Yes. Add the /NoTel parameter, for example setupdiag.exe /NoTel, to stop telemetry for that run.
What if SetupDiag says it found no matching issue?
Make sure you run the latest version and that the log folders still exist. If it still finds nothing, the failure is not covered by its rules and the logs need manual analysis.
Related: using the Windows 11 Media Creation Tool, what Microsoft Update Health Tools does, whether to install Windows preview updates
I get this error:
SetupDiag was unable to find a relevant log file.
And all attempts to update my windows to build 1903 fail don’t report any error
DISM.exe /Online /Cleanup-image /Restorehealth
sfc /scannow
but the update fails.
I don’t have any strange driver.
SetupDiag: Main() failed with an unhandled exception
„C:\$WINDOWS.~BT\Sources\Panther\%systemdrive%\debuggersâ€.
Source: mscorlib
Stack: System.IO.__Error.WinIOError(Int32 errorCode, String maybeFullPath)
Broken like the update itself.
tnx 1709 is failing constantly on this machine, but let me without a clue why.
i’ll check this one out.
I had hoped this would provide a solution to my gf laptop that won’t make it to Windows 10 1709… Sigh.
8:59:13 – SetupDiag: Main() failed with an unhandled exception:
Same question like Bill Steiner.
Where can you download the SetupDiag.exe file?
i was wondering the same thing. is this Software we download and if so where is the link? Or is this something already in Windows 10 and we just run the command? The article make me think were supposed to download and install something, as the article says – “You can run SetupDiag directly after download.”
Rick, you go to the Microsoft Docs website mentioned in the article: https://docs.microsoft.com/en-us/windows/deployment/upgrade/setupdiag#requirements
It contains a link called SetupDiag.exe near the top which downloads the file to your system.
Alright, Thanks.
There’s a link at the bottom to Microsoft Docs. Click that, scroll up for the download link.
2:50:56 – SetupDiag: Main() failed with an unhandled exception:
The path is not of a legal form.
Exception System.ArgumentException: The path is not of a legal form.
Source: mscorlib
Stack: at System.IO.Path.LegacyNormalizePath(String path, Boolean fullCheck, Int32 maxPathLength, Boolean expandShortPaths)
at System.IO.Path.NormalizePath(String path, Boolean fullCheck, Int32 maxPathLength, Boolean expandShortPaths)
at System.IO.Path.InternalGetDirectoryName(String path)
at Microsoft.Internal.Deployment.SetupDiag.Directive.DirectiveDebugMemoryDump()
at Microsoft.Internal.Deployment.SetupDiag.Directive.DoDirective()
at Microsoft.Internal.Deployment.SetupDiag.CSetupDiag.RunDiag(String strRulesFile, String strlogsPath, String strMode, String strOutPut, String strFormat, String resLevel, Boolean fCreateLogs)
at Microsoft.Internal.Deployment.SetupDiag.Program.Main(String[] args)
About 6 mon. ago I got a laptop with 1607 on it. I was just starting to learn Win 10, then it kept failing at updating to 1703, let alone 1709. I used all MS troubleshooters I could find, but only when I stumbled on what I think was called MS ‘upgrader’ did it shoot me all the way to latest build 1709, in one update. Hope the ‘Spring’ one goes smoothy-woothy.