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. Prüfen ob TLS 1.2 verfügbar ist:

   [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.