windows-updater/docs/troubleshooting.md

Problembehandlung

PSWindowsUpdate-Modul lässt sich nicht laden

Symptom

[ERROR] Failed to load PSWindowsUpdate module from any source

Lösungen

Online-Installation schlägt fehl:

1. Das Script setzt TLS 1.3 (bevorzugt) mit TLS 1.2 als Fallback. Auf älteren Systemen (z.B. Windows 10 ohne aktuelles .NET) wird TLS 1.3 ignoriert und TLS 1.2 genutzt. Aktiven Protokollstatus prüfen:

   [Net.ServicePointManager]::SecurityProtocol
   

2. NuGet-Provider manuell installieren:

   Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force
   

3. PSGallery als vertrauenswürdige Quelle setzen:

   Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
   

4. Proxy prüfen (falls vorhanden):

   [System.Net.WebRequest]::DefaultWebProxy
   

Offline-Fallback schlägt fehl:

• Prüfen ob der Ordner Modules\PSWindowsUpdate im Script-Verzeichnis existiert
• Prüfen ob die DLL-Datei vorhanden ist: Modules\PSWindowsUpdate\2.2.1.2\PSWindowsUpdate.dll

Keine Updates gefunden

Mögliche Ursachen

1. WSUS blockiert Updates:

   • Script zeigt "WSUS server detected" im Log
   • WSUS-Server hat möglicherweise keine Updates freigegeben
   • Lösung: WSUS-Administrator kontaktieren oder UseMicrosoftUpdate = true setzen (funktioniert nur ohne WSUS-GPO)

2. Windows Update Service gestoppt:

   Get-Service wuauserv | Select-Object Status
   # Falls gestoppt:
   Start-Service wuauserv
   

3. Updates bereits installiert:

   • Das Script zeigt "No updates available" — alle Updates sind aktuell

E-Mail wird nicht gesendet

Checkliste

1. SMTP-Server erreichbar?

   Test-NetConnection -ComputerName smtp.example.com -Port 587
   

2. Zugangsdaten korrekt? Im Log nach folgender Meldung suchen:

   [WARN] Failed to send email: ...
   

3. App-Passwort bei Gmail/Microsoft 365:

   • Normales Passwort funktioniert oft nicht
   • App-spezifisches Passwort in den Kontoeinstellungen erstellen

4. Firewall: Port 587 (oder 465/25) muss ausgehend offen sein

5. SSL/TLS: SmtpUseSsl = true für Port 587/465, false für Port 25 (lokal)

ntfy-Benachrichtigung kommt nicht an

Checkliste

1. Server erreichbar?

   Invoke-RestMethod -Uri "https://ntfy.sh/test-topic" -Method Post -Body "Test"
   

2. Topic korrekt? Topic-Name muss in Config und App identisch sein

3. Token korrekt? Falls Authentifizierung konfiguriert:

   $headers = @{ "Authorization" = "Bearer tk_mein_token" }
   Invoke-RestMethod -Uri "https://ntfy.mein-server.de/test" -Method Post -Body "Test" -Headers $headers
   

4. App abonniert? In der ntfy-App prüfen ob das Topic abonniert ist

Winget wird nicht erkannt

Auf Client-Systemen (Windows 10/11)

1. Winget installiert?

   Get-Command winget
   # oder
   Get-AppxPackage -Name Microsoft.DesktopAppInstaller
   

2. Winget aktualisieren:

   • Microsoft Store öffnen → "App-Installer" aktualisieren

3. Im SYSTEM-Kontext: Winget ist eine per-User MSIX-App. Das Script versucht automatisch den Pfad über Get-AppxPackage -AllUsers zu finden.

Auf Server-Systemen

Winget ist auf Windows Server standardmäßig nicht verfügbar. Es kann manuell installiert werden:

1. Aktuelle Version von GitHub herunterladen
2. .msixbundle installieren (erfordert ggf. zusätzliche Abhängigkeiten)

Das Script erkennt automatisch ob winget verfügbar ist und überspringt die Funktion wenn nicht.

ImportExcel / XLSX-Export funktioniert nicht

Symptom

[WARN] ImportExcel not available, falling back to CSV for history export

Lösungen

1. Manuell installieren:

   Install-Module -Name ImportExcel -Force -Scope AllUsers
   

2. Kein Internet: Das Script versucht automatisch das Modul zu installieren. Ohne Internet wird automatisch CSV als Fallback verwendet.

3. CSV statt XLSX: Funktioniert immer, keine zusätzlichen Module nötig. Die History-Datei wird dann als .csv statt .xlsx gespeichert.

Script bricht mit "must be run as Administrator" ab

Das Script erfordert Administrator-Rechte für:

• Installation von Windows Updates
• Installation von PowerShell-Modulen
• Zugriff auf Windows Update COM-Objekte

Lösung

• PowerShell als Administrator starten (Rechtsklick → "Als Administrator ausführen")
• In der Aufgabenplanung: "Mit höchsten Privilegien ausführen" aktivieren und als SYSTEM ausführen

Updates schlagen wiederholt fehl

Mögliche Ursachen

1. Speicherplatz: Windows Updates benötigen freien Speicher

   Get-PSDrive C | Select-Object Used, Free
   

2. Windows Update Komponenten zurücksetzen:

   # PSWindowsUpdate bietet dafür ein Cmdlet
   Reset-WUComponents -Verbose
   

3. Bestimmte KB ausschließen: Falls ein spezifisches Update immer fehlschlägt:

   [WindowsUpdate]
   ExcludeKBs = KB1234567
   

4. Retry-Count erhöhen: Manchmal hilft ein weiterer Versuch:

   [WindowsUpdate]
   RetryCount = 5
   

Log-Dateien werden nicht erstellt

1. Verzeichnis-Berechtigungen prüfen:

   # SYSTEM muss Schreibrechte haben
   icacls "C:\logs\windows-updater"
   

2. Verzeichnis erstellen:

   New-Item -ItemType Directory -Path "C:\logs\windows-updater" -Force
   

3. LogPath in config.ini prüfen — Pfad muss ohne Anführungszeichen angegeben werden

Hook-Scripts werden nicht ausgeführt

1. Pfad korrekt? Absoluter Pfad verwenden, keine Umgebungsvariablen
2. Script vorhanden? Test-Path auf den konfigurierten Pfad prüfen
3. Execution Policy: Hook-Scripts werden mit -ExecutionPolicy Bypass aufgerufen
4. Exit-Code: Hook muss mit exit 0 enden für Erfolg, jeder andere Code gilt als Fehler

Allgemeine Diagnose

Log-Ausgabe im Detail prüfen

# Heutiges Log anzeigen
$today = Get-Date -Format "yyyy-MM-dd"
Get-Content "C:\logs\windows-updater\windows-updater_$today.log"

# Nach Fehlern suchen
Select-String -Path "C:\logs\windows-updater\windows-updater_*.log" -Pattern "\[ERROR\]"

Script manuell mit Ausgabe testen

# In einer Admin-PowerShell ausführen
powershell.exe -ExecutionPolicy Bypass -File "C:\scripts\windows-updater\windows-updater.ps1"

Dry-Run zum Testen

In config.ini setzen:

[General]
DryRun = true

Dies prüft alle Funktionen (Logging, Benachrichtigungen, Modulladung) ohne tatsächlich Updates zu installieren.