Skip to content

installer-diagnostics.md

Latest commit

 

History

History
93 lines (66 loc) · 5.14 KB

installer-diagnostics.md

File metadata and controls

93 lines (66 loc) · 5.14 KB

PowerToys Installer & Update Diagnostics

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

Quick Reference: Key Files

File/Folder Path Contains
UpdateState.json %LOCALAPPDATA%\Microsoft\PowerToys\UpdateState.json Persisted update state machine
Runner logs %LOCALAPPDATA%\Microsoft\PowerToys\RunnerLogs\runner-log_*.log Startup, update checks, cleanup
Update logs %LOCALAPPDATA%\Microsoft\PowerToys\UpdateLogs\update-log_*.log PowerToys.Update.exe activity
Updates folder %LOCALAPPDATA%\Microsoft\PowerToys\Updates\ Downloaded installer 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):

Value Name Meaning
0 upToDate No update needed
1 errorDownloading Download or install failed, will retry
2 readyToDownload New version found, not yet downloaded
3 readyToInstall Installer downloaded, waiting for user action
4 networkError GitHub API call failed

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", ...}
  • 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:

Log pattern Meaning
Failed to delete installer file ... Access is denied File locked by AV, another process, or permissions issue
Failed to delete log file ... Same, for old log files
Discovered new version Periodic update check ran
New version is already downloaded State is readyToInstall and filename matches — no re-download, no cleanup
No cleanup-related entries at all Inconclusive by itself — cleanup_updates() is silent on success. Corroborate with the Updates folder contents (Step 5) and the running version (Step 1).

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

Root cause Evidence Fix
Running pre-v0.73.0 binary product_version < v0.73.0 in runner log Manually upgrade to latest
State stuck at readyToInstall (pre-v0.73) state: 3 in UpdateState.json, no UpdateLogs Manually upgrade to latest
File lock preventing deletion "Failed to delete ... Access is denied" in runner logs Check AV software, reboot and retry
Update installer never launched No UpdateLogs directory Check if update notifications are disabled by GPO or setting
Install fails silently UpdateLogs show init but no install activity Check related issues: #46966, #46967, #46969