windows-iac-vm-tooling/docs/07-advanced/troubleshooting.md

🔧 Troubleshooting Guide

Overview

This guide covers common issues and their solutions for the Windows automation pipeline.

---

Quick Fix Index

Issue	Phase	Quick Fix
Packer timeout	Build	Check Autounattend.xml WinRM config
VM won't boot	Provision	Verify ISO paths in Packer
Ansible connection	Test	Disable Windows firewall
Code signing fails	Build	Verify PFX password
Template expired	All	Rebuild with Packer

---

Phase 1: Packer Issues

Timeout Waiting for WinRM

Symptom:

==> proxmox-iso.windows-11: Timeout waiting for WinRM.

Cause: Windows not fully booted or WinRM not configured.

Solution:

1. Verify Autounattend.xml has WinRM configuration
2. Check boot command timing
3. Increase boot_wait duration

# Increase boot wait
boot_wait = "30s"

# Check boot command
boot_command = [
  "<wait><wait><wait><wait><wait>",
  "<enter><wait><wait>",
  "<enter>"
]

---

ISO Not Found

Symptom:

==> proxmox-iso.windows-iso: ISO file not found: local:iso/...

Cause: Wrong ISO path or storage.

Solution:

1. Verify ISO location on Proxmox
2. Check storage name (local vs local-lvm)

# On Proxmox host
ls -la /mnt/pve-07-iso-nvme/template/iso/
qm storage

---

Phase 2: OpenTofu Issues

Clone Failed

Symptom:

Error: resource is not a cloneable VM

Cause: Wrong VM ID or template not found.

Solution:

1. Verify template VM exists
2. Check VM ID is correct

# On Proxmox host
qm list | grep template

---

Permission Denied

Symptom:

Error: permission denied (400)

Cause: Proxmox API token lacks privileges.

Solution:

1. Add VM.Admin role to token
2. Verify token is not expired

---

Phase 3: Ansible Issues

WinRM Connection Timeout

Symptom:

fatal: [10.0.0.5]: UNREACHABLE! => {"msg": "Connection timeout"}

Cause: Firewall blocking WinRM or WinRM not configured.

Solution:

# In Autounattend.xml - disable firewall
<SynchronousCommand wcm:action="add">
  <CommandLine>powershell -Command "Set-NetFirewallProfile -Profile Private -Enabled False"</CommandLine>
  <Order>1</Order>
</SynchronousCommand>

# In inventory - ignore certificate validation
[windows_vm]
10.0.0.5 ansible_winrm_server_cert_validation=ignore

---

Invalid Credentials

Symptom:

fatal: [10.0.0.5]: UNREACHABLE! => {"msg": "Basic auth failed"}

Cause: Wrong username or password.

Solution:

# Verify secrets are set
echo $WIN_ADMIN_PASS

# Test manually
winrs -r:10.0.0.5 -u:Administrator -p:$WIN_ADMIN_PASS "hostname"

---

Phase 4: Code Signing Issues

Invalid Certificate

Symptom:

Error: PKCS12_parse failed

Cause: Wrong password or corrupted PFX file.

Solution:

# Verify certificate
openssl pkcs12 -in cert.pfx -info -noout -passin pass:$PFX_PASS

---

Diagnostic Commands

Proxmox Diagnostics

# List VMs
qm list

# Check VM status
qm status <VM_ID>

# View VM config
qm config <VM_ID>

# Check storage
pvesm status

Windows Diagnostics

# Check WinRM status
winrm quickconfig
Get-WinRM -Service

# Check firewall
Get-NetFirewallProfile | Select Name, Enabled

# Check activation
slmgr /dlv

Ansible Diagnostics

# Test WinRM connection
ansible windows_vm -m win_ping -i inventory.ini

# Verbose output
ansible-playbook -i inventory.ini pipeline.yml -vvvv

---

Log Locations

Component	Log Location
Packer	Console output + packer.log
OpenTofu	Console output + .terraform.lock.hcl
Ansible	Console output + /var/log/ansible.log
Windows	Event Viewer → System

---

FAQ

Q: Can I use a different Windows edition?

A: Yes, but you need to:

1. Update ISO in packer/windows.pkr.hcl
2. Modify Autounattend.xml for that edition
3. Update product key settings

Q: How do I add more software to the template?

A: Add PowerShell provisioners:

provisioner "powershell" {
  inline = [
    "choco install -y 7zip git vscode",
    "& 'C:\\ProgramData\\Chocolatey\\bin\\choco.exe' install -y dotnetfx"
  ]
}

Q: The VM has no IP after provisioning

Cause: DHCP not working or VirtIO drivers missing.

Solution:

1. Ensure VirtIO drivers are installed in template
2. Verify network bridge is correct

---

Next Steps

Goal	Next Document
Manage evaluations	Evaluation Management
View pipeline	Forgejo Workflows
Full documentation	Documentation Index

---

← Documentation Index | ← Evaluation Management | ← Home