PowerToys Installer & Update Diagnostics

A step-by-step guide for diagnosing installer and update issues reported by users.

Quick Reference: Key Files

Note: These paths use %LOCALAPPDATA% (per-user AppData) regardless of whether PowerToys was installed per-user or per-machine. The data/settings location is always per-user.

Update State Values

From src/common/updating/updateState.h (UpdateState::State enum):

Symptom: Old update installers accumulating on disk

What to ask the user for

1. Contents of UpdateState.json
2. Runner logs (last few days from RunnerLogs\)
3. Update logs (from UpdateLogs\, if they exist)
4. List of files in Updates\ folder (names + sizes)

Step 1: Check the running version

In runner logs, look for the startup line:

[info] Scoobe: product_version=v0.XX.X last_version_run=v0.XX.X

• If version < v0.73.0: The pre-download cleanup (PR #27908) is missing. Each downloaded installer accumulates because cleanup only runs at startup when state is upToDate. Ask the user to manually upgrade to the latest version.
• If version >= v0.73.0: The pre-download cleanup exists. Accumulation should not happen under normal conditions. Continue to Step 2.

Step 2: Check UpdateState.json

{"state": 3, "downloadedInstallerFilename": "powertoyssetup-0.98.1-x64.exe" /* additional fields may be present */}

• state = 0 (upToDate): Cleanup should run at startup. If files are accumulating, check runner logs for "Failed to delete" warnings (Step 4).
• state = 3 (readyToInstall): An installer is downloaded but never installed. Cleanup at startup is skipped (by design, to preserve the pending installer). On v0.73+, cleanup can still occur when a future update check triggers a new download (pre-download cleanup path).
• state = 1 (errorDownloading): A previous download or install failed. Startup cleanup is skipped (state is not upToDate). On v0.73+, cleanup runs before the next installer download is attempted.
• state = 2 or 4: Startup cleanup is skipped. On v0.73+, cleanup runs before the next installer download is attempted.

Step 3: Check if PowerToys.Update.exe has ever run

• UpdateLogs directory missing: This suggests PowerToys.Update.exe may never have been launched, or it did not progress far enough to create logs. The user may never have triggered an install, or Stage 1 may have failed before Stage 2 could run.
• UpdateLogs exist but show only "logger is initialized": The exe launched but the command-line argument didn't match any action (possible argument parsing issue).
• UpdateLogs show install activity: The update process ran. Check for success/failure.

Step 4: Check runner logs for cleanup evidence

Search for these patterns:

Step 5: Check the Updates folder contents

• All different versions: Cleanup likely did not run across multiple update cycles. Confirm with the running version (Step 1) and update state before concluding a state gate issue.
• Duplicate filenames: Unusual — would suggest repeated download without cleanup.
• Single file matching downloadedInstallerFilename: Normal for readyToInstall state.

Common root causes