Skip to content

Troubleshooting

1. No network in WinPE

Symptom: Start-Deploy.ps1 can't reach \\SERVER\Deploy.

Checks:

  • Confirm the correct NIC drivers were injected into the WinPE image for that hardware model (Modules/Drivers/<model>).
  • Run wpeutil InitializeNetwork manually from the WinPE command prompt.
  • Verify the share and NTFS permissions allow the account used by New-SmbMapping.

2. Orphaned DISM mounts

Symptom: dism /Mount-Image fails with "already mounted" or the mount folder is stuck.

Fix:

dism /Cleanup-Wim
dism /Unmount-Image /MountDir:C:\mount /Discard

If the folder is still locked, reboot the build machine before retrying.

3. Sequence doesn't resume after reboot

Symptom: the machine reboots but the sequence doesn't continue automatically.

Checks:

  • Confirm the RunOnce registry key was created (HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\RunOnce) pointing to Start-Deploy.ps1 -Resume.
  • Check the state file used to track progress hasn't been deleted or is on a share unreachable from Windows (not just WinPE).
  • Verify WinPE.MaxReboots in PSWinDeploy.psd1 hasn't been exceeded — the anti-loop guard stops the sequence silently once past the threshold.

4. Pode API doesn't start / isn't reachable

Checks:

  • Get-Module Pode -ListAvailable — confirm it's installed for the account running the service.
  • Firewall rule for the configured port (default 8080).
  • If run via NSSM, check nssm status PSWinDeployAPI and the service's stdout/stderr log files.
  • Test locally first: curl http://localhost:8080/api/health.

5. DPAPI vault unreadable on another machine

Symptom: credential lookup silently falls back to an interactive prompt on a different machine.

Cause: DPAPI ties encryption to the Windows account + machine that created the vault. See Secrets Vault.

Fix: recreate the vault using AES with a shared password instead of DPAPI.

6. Logs

Deployment logs are written to \\SERVER\Logs, one file per runtimeId. The API also exposes the tail of a running deployment's log via GET /api/deploy/logs/:id, and the web UI streams it live on the "Deployment" page.