Troubleshooting

Troubleshooting

"Not running as administrator"

Most groups need admin (services, registry, fonts, power plan). Use sudo on Windows 11, or the fallback launcher:

powershell -NoProfile -ExecutionPolicy Bypass -File ".\setup.ps1"

To enable native sudo on Windows 11: Settings → System → For developers → Enable sudo. See docs/ADMIN-PRIVILEGES.md.

"running scripts is disabled on this system"

Execution policy is blocking the script. Run it with a bypass for the single session (does not change system settings):

powershell -NoProfile -ExecutionPolicy Bypass -File ".\setup.ps1"

winget is not recognized

Install App Installer from the Microsoft Store (Windows 10), or update it on Windows 11. winforge falls back to Chocolatey and then a custom URL if winget is unavailable, but winget is the primary path.

A program did not install

Re-run just that group and read the log lines:

sudo .\setup.ps1 -Group <group>

Then confirm detection with the validator (installs nothing):

.\tools\validate.ps1 -Group <group> -ShowDetails

If winget reports success but the app is missing, try Chocolatey manually (choco install <id>) or the vendor installer.

Re-running is safe

Detection is idempotent — installed programs are skipped and configuration blocks re-apply cleanly, so you can run setup.ps1 as many times as needed.

Undoing optimizations

The optimize tweaks are reversible via Windows settings and service controls. See Optimization Details → Reverting.