Debugging und Fehlersuche
Quelle: pkr-lab/pkr-lab-docs/DocFlowEngine/debugging.md
Debugging und Fehlersuche
Code: scripts/DocFlowEngine/, scripts/DocFlowEngine.psm1, scripts/Rename-ExistingAufgaben.ps1, scripts/Invoke-OneDriveSync.ps1
Diese Seite sammelt alle Fehler- und Warnmeldungen des Codes und führt durch die Fehlersuche. Die Beschreibung der Log-Ausgabe steht in Logging, die häufigsten Fehlerbilder in der Nutzung. Das projektübergreifende Kapitel ist die zentrale Fehlersuche.
Wo man Fehler findet
| Quelle | Inhalt |
|---|---|
Konsole (Write-Host) |
jede Meldung ab dem eingestellten Level, im Format [JJJJ-MM-TT HH:mm:ss] [LEVEL] Text |
Log-Datei (log.file, Standard ./docflow.log) |
dieselben Zeilen per Add-Content. Im -DryRun wird das Log-Verzeichnis nicht angelegt, ein vorhandenes wird aber beschrieben (Logging) |
.docflow-state.json (stateFile) |
welche Quelldateien als verarbeitet gelten (Schlüssel Quellpfad\|relativer Pfad, kleingeschrieben) |
Lock-Datei (lockFile) |
Inhalt Rechnername\|PID\|Zeitstempel, zeigt, wer zuletzt gelaufen ist |
| Hinweisdateien neben den Schülerdateien | Rückmeldung an den Schüler (Naming-Hinweis, Duplikat-Hinweis) |
-Verbose / -Debug |
ohne Wirkung: Der Code nutzt weder Write-Verbose noch Write-Debug. Den Detailgrad steuert allein log.level (Trace bis Error) |
Log-Level für die Fehlersuche: log.level = 'Debug' zeigt zusätzlich die vollständige Whitelist, Trace den größten Detailgrad. Im Normalbetrieb genügt Info.
Warum wurde meine Datei nicht kopiert?
flowchart TD
A[Datei im Quellordner] --> B{ausgeschlossen? Ziel- oder aufgabenRoot-Ordner, Ordner Korrigiert, Hinweisdatei}
B -->|ja| X1[stillschweigend ignoriert]
B -->|nein| C{laut Zustand schon verarbeitet?}
C -->|ja, gleiche Größe und Zeit| X2[übersprungen, nur Zähler Bereits in früheren Läufen verarbeitet]
C -->|ja, aber geändert| X3[Warnung: nach der Abgabe überschrieben, keine Kopie, Duplikat-Hinweis]
C -->|nein| D{zu jung oder gesperrt minFileAgeMinutes?}
D -->|ja| X4[Info: im nächsten Lauf]
D -->|nein| E{aufgabenRoot: Schema und Whitelist ok?}
E -->|nein, Hinweis aktiv| X5[Warnung: passt nicht zum Schema oder nicht in der Whitelist, Hinweisdatei]
E -->|ja| F[Ziel aufgabenRoot/Präfix/Suffix]
E -->|kein aufgabenRoot| G{Kategorie-Routing?}
G -->|aktiv, kein Treffer| X6[Warnung: keine Zuordnung, übersprungen]
G -->|keine Routen, keine targets| X7[Warnung: kein Ziel ermittelbar]
G -->|Treffer oder targets| F
F --> H{Abgabe im Ziel vorhanden?}
H -->|gleich groß| X8[Info: liegt bereits identisch, als verarbeitet übernommen]
H -->|andere Größe| X9[Warnung: bereits abgegeben, Duplikat-Hinweis]
H -->|nein| I{Zieldatei existiert?}
I -->|ja| X10[Warnung: Zieldatei existiert bereits]
I -->|nein| J[Kopie mit Wiederholungen copyRetry, Größenprüfung]
J -->|alle Versuche gescheitert| X11[Error: im nächsten Lauf erneut]
J -->|ok| K[Zustand schreiben, Hinweisdateien entfernen]
Mit -DryRun lässt sich jeder dieser Schritte ohne Änderung nachvollziehen. Dann steht bei jeder geplanten Aktion [DryRun] in der Meldung, und Zustand, Sperre und Dateien bleiben unberührt (Hinweisdateien werden nur als „würde erstellt“ gemeldet).
Fehlermeldungen
Abbruch bei Start oder Konfiguration (throw)
Diese Meldungen beenden den Lauf mit einem PowerShell-Fehler.
| Meldung | Ursache | Lösung |
|---|---|---|
Teilmodul '<pfad>' wurde nicht gefunden. |
eine der sieben Teildateien unter scripts/DocFlowEngine/ fehlt (Checkout unvollständig oder Dateien verschoben) |
Repo vollständig auschecken, Struktur prüfen |
Konfigurationsdatei '<pfad>' wurde nicht gefunden. |
-ConfigPath zeigt ins Leere (Standard .\config\docflow-config.psd1 ist relativ zum aktuellen Verzeichnis) |
absoluten Pfad angeben oder im Projektverzeichnis starten |
Konfiguration muss mindestens einen Eintrag unter 'sources' enthalten. |
sources leer oder fehlt |
Quellordner ergänzen (Konfiguration) |
Konfiguration braucht 'aufgabenRoot' oder mindestens einen Eintrag unter 'targets'. |
weder aufgabenRoot noch targets |
eines von beiden angeben |
Konfiguration muss mindestens eine Regel unter 'namingConventions' enthalten. |
namingConventions leer oder fehlt |
Regel ergänzen (Konfiguration) |
Pfad-Variable '{<name>}' ist in 'paths' nicht definiert. |
Platzhalter {name} in einem Pfad ohne passenden Eintrag unter paths |
paths ergänzen oder Schreibweise prüfen |
Pfad-Variable '{<name>}' in '<feld>' ist in 'paths' nicht definiert. |
wie oben, mit Feldangabe | wie oben |
Zirkulärer Verweis in 'paths' bei '{<name>}'. |
zwei Pfad-Variablen verweisen aufeinander | Verweis auflösen |
Pfad '<wert>' enthält Wildcards, aber es konnte kein existierendes übergeordnetes Verzeichnis dafür gefunden werden. |
Pfad mit * oder ?, dessen fester Anteil nicht existiert (zum Beispiel OneDrive nicht eingebunden) |
Pfad prüfen, OneDrive-Sync abwarten |
Zielverzeichnis '<pfad>' existiert nicht und createIfMissing ist false. |
targets[].createIfMissing = $false und der Ordner fehlt |
Ordner anlegen oder createIfMissing auf $true |
Parse-Fehler beim Import der .psd1 |
ungültige Hashtable-Syntax | Import-PowerShellDataFile -Path .\config\docflow-config.psd1 ausführen und die Zeile aus dem Fehler korrigieren |
Skripte Rename-ExistingAufgaben.ps1 und Invoke-OneDriveSync.ps1
| Meldung | Ursache | Lösung |
|---|---|---|
Moduldatei '<pfad>' wurde nicht gefunden. |
DocFlowEngine.psm1 nicht neben dem Skript |
Skript im Verzeichnis scripts/ belassen |
Undo-Datei '<pfad>' wurde nicht gefunden. |
falscher Pfad bei -Undo |
Pfad der Bericht-CSV prüfen |
Pfad '<eintrag>' wurde nicht gefunden. |
Eintrag in -Path existiert nicht |
Pfad korrigieren |
Kein Ordner zum Durchsuchen gefunden. -Path angeben oder 'sources' in der Konfiguration prüfen. |
kein -Path und keine auflösbare Quelle in der Konfiguration |
-Path angeben |
Abgebrochen: eine andere DocFlowEngine-Instanz ist aktiv (Lock-Datei '<pfad>'). (Warnung) |
Lock ist frisch, ein Lauf auf einem anderen Rechner oder Task läuft | warten oder Lock-Datei prüfen |
Nicht mehr vorhanden, übersprungen: '<pfad>' (beim Undo) |
die umbenannte Datei existiert nicht mehr | kein Fehler, nur Hinweis |
Alter Name ist bereits wieder belegt, übersprungen: '<pfad>' (beim Undo) |
unter dem früheren Namen liegt inzwischen eine andere Datei | manuell klären |
Konnte '<pfad>' nicht zurückbenennen: <detail> |
Rechte oder gesperrte Datei | Detail lesen, Datei freigeben |
OneDrive.exe wurde nicht gefunden (gesucht unter '<pfad>'). Ueberspringe Sync-Anstoss. (Warnung, Exit-Code 0) |
OneDrive nicht an der Standardstelle | -ExecutablePath angeben, oder die Aufgabe weglassen |
Meldungen im Lauf (Level Warning und Error)
| Meldung | Level | Ursache | Lösung |
|---|---|---|---|
Verarbeitung übersprungen, da eine andere Instanz aktiv ist. |
Warning | folgt auf die Lock-Meldung, der Lauf endet ohne Arbeit | siehe Lock |
Lauf abgebrochen: aktive Lock-Datei '<pfad>' gefunden (<rechner>\|<pid>\|<zeit>). |
Warning | Lock jünger als lockTimeoutMinutes (Standard 15) |
warten, bis der andere Lauf endet oder der Timeout abläuft. Bei abgestürztem Lauf Datei löschen. Bei geteiltem Ordner siehe Multi-Machine |
Quellverzeichnis '<pfad>' existiert nicht oder wurde nicht gefunden. Überspringe. |
Warning | Quelle nicht vorhanden (OneDrive nicht synchronisiert, Tippfehler) | Pfad prüfen |
Zustandsdatei '<pfad>' konnte nicht gelesen werden. Es wird eine neue Datei erstellt. |
Warning | beschädigtes JSON in .docflow-state.json |
Datei sichern, Lauf wiederholen. Alle Dateien gelten danach als neu und können erneut kopiert werden. Ob sie im Ziel schon liegen, entscheidet die Prüfung „liegt bereits identisch“ |
Registry-Datei '<pfad>' wurde nicht gefunden. |
Warning | projectRoutesFile zeigt auf eine fehlende Datei |
Pfad prüfen oder Startbestand per projectRoutesSeedFile angeben |
Whitelist-Startbestand '<pfad>' wurde nicht gefunden. Synchronisierung übersprungen. |
Warning | projectRoutesSeedFile fehlt |
Pfad prüfen |
Ungültige Zeile in Whitelist '<pfad>' ignoriert (erlaubt: praefix=<Name>, suffix=<Name>): '<zeile>' |
Warning | Zeile in project-routes.txt hat falsche Form |
Zeile korrigieren |
Suffix '<name>' in Whitelist '<pfad>' steht vor dem ersten praefix= und wird ignoriert. (beim Abgleich: … wird beim Abgleich entfernt.) |
Warning | Suffix ohne Präfix | praefix=<Name> davor setzen |
Datei '<name>': Präfix '<p>' ist nicht in der Whitelist '<pfad>' eingetragen. |
Warning | Präfix unbekannt | Whitelist ergänzen oder dem Schüler das richtige Präfix nennen |
Datei '<name>': Suffix '<s>' ist für Präfix '<p>' nicht in der Whitelist '<pfad>' eingetragen. |
Warning | Kombination nicht erlaubt | Whitelist ergänzen |
Datei '<name>' passt nicht zum Schema initialen[_v<version>]_praefix_suffix_aufgabennummer (…). |
Warning | Name verletzt das Schema (Leerzeichen, Bindestrich, Umlaut, fehlender Teil) | Datei umbenennen. Der Schüler findet die Hinweisdatei neben der Datei |
Keine passende Kategorie-Zuordnung für '<name>' gefunden. Datei wird übersprungen. |
Warning | categoryRoutes aktiv, aber kein Treffer |
Routing erweitern oder Dateinamen korrigieren |
Kein Ziel für '<name>' ermittelbar (kein gültiges Präfix/Suffix-Routing, keine 'targets' konfiguriert). Datei wird übersprungen. |
Warning | weder aufgabenRoot-Routing noch targets |
targets konfigurieren oder Namen korrigieren |
Datei '<name>' wurde nach der Abgabe unter gleichem Namen überschrieben. Sie wird nicht erneut kopiert; der Schüler soll eine Versionsangabe (_v2_ usw.) verwenden. |
Warning | bereits verarbeitete Datei wurde geändert | Version im Namen (_v2_) verwenden |
Datei '<name>' wurde bereits abgegeben ('<vorhanden>'). Sie wird nicht erneut kopiert; … |
Warning | im Ziel liegt schon eine andere Abgabe | wie oben |
Zieldatei existiert bereits, überspringe Kopie: '<pfad>' |
Warning | Ziel existiert (zum Beispiel durch einen anderen Rechner) | normal bei Multi-Machine-Betrieb |
Kopierversuch N von M fehlgeschlagen: '<quelle>' -> '<ziel>' (<detail>). Neuer Versuch in S Sekunden. |
Warning | Kopie scheiterte, wird wiederholt | Detail lesen, oft gesperrte Datei |
Kopieren nach M Versuchen fehlgeschlagen: '<quelle>' -> '<ziel>' (<detail>). Wird beim nächsten Lauf erneut versucht. |
Error | alle Versuche scheiterten | Detail lesen (Rechte, Pfadlänge, Speicherplatz) |
Zieldatei hat X Bytes, Quelle Y Bytes. (im Detail der Kopier-Meldung) |
Error/Warning | Größenprüfung nach dem Kopieren schlug fehl, Datei wurde beim Kopieren geändert | erneut laufen lassen |
Verzeichnis konnte nicht erstellt werden: '<pfad>' (<detail>). '<name>' wird beim nächsten Lauf erneut versucht. |
Error | Rechte oder Pfad ungültig | Berechtigung und Pfadlänge prüfen |
<Meldung> Hinweis-Datei konnte nicht erstellt werden: '<pfad>' (<detail>) |
Error | keine Schreibrechte im Quellordner | Rechte prüfen |
Hinweis-Datei konnte nicht entfernt werden: '<pfad>' (<detail>) |
Warning | Datei gesperrt oder schreibgeschützt | manuell löschen |
Kein Schülerordner für '<name>' ermittelbar (erkanntes Kürzel aus dem Dateinamen: '<kürzel>') - Rückkopie übersprungen. |
Warning | Kürzel nicht registriert | Kürzel erst über eine Abgabe registrieren lassen oder Registry ergänzen, siehe unknownKuerzelHint |
Verzeichnis konnte nicht erstellt werden: '<korrigiert-ordner>' (<detail>). Rückkopie von '<name>' wird beim nächsten Lauf erneut versucht. |
Error | Ordner „Korrigiert“ nicht anlegbar | Rechte prüfen |
Die Info-Meldungen (zum Beispiel „wurde vor weniger als N Minuten geändert“ oder „ist gerade gesperrt“) sind keine Fehler: Die Datei wird im nächsten Lauf verarbeitet. Eine Übersicht der normalen Meldungen steht unter Logging.
Checkliste „Feature funktioniert nicht“
- Konfiguration lesen:
Import-PowerShellDataFile -Path .\config\docflow-config.psd1ohne Fehler? Stimmensources,aufgabenRoot,namingConventions? - Trockenlauf:
Invoke-DocFlowEngine -ConfigPath <pfad> -DryRunund das Log lesen. Was steht für die betroffene Datei? - Quelle da? Meldung
Quellverzeichnis … existiert nichtoderGefundene Dateien in '…': 0? - Name prüfen: Schema
initialen[_v<version>]_praefix_suffix_aufgabennummer, nur Buchstaben und Ziffern. Präfix und Suffix in der Whitelist (Namenskonvention,project-routes.txt)? - Alter und Sperre: Datei jünger als
minFileAgeMinutes(Standard 2) oder noch in Synchronisierung? - Zustand: Steht die Datei in
.docflow-state.json? Dann gilt sie als verarbeitet. Zum erneuten Kopieren den Eintrag entfernen (Datei sichern). - Lock: Lock-Datei frisch? Läuft ein anderer Rechner? (Multi-Machine)
- Rechte: Schreibrechte im Ziel und (für Hinweisdateien) im Quellordner?
- Mehrere Rechner: Zeigen
stateFile,lockFileundprojectRoutesFileauf einen geteilten Ordner? - PowerShell-Version:
$PSVersionTable.PSVersion(5.1 oder neuer), siehe Kompatibilität.
Lokal debuggen
# Konfiguration prüfen
Import-PowerShellDataFile -Path .\config\docflow-config.psd1
# Vorschau, ändert nichts
Import-Module .\scripts\DocFlowEngine.psm1 -Force
Invoke-DocFlowEngine -ConfigPath .\config\docflow-config.psd1 -DryRun
# Mit höchstem Detailgrad: log.level = 'Trace' in der Konfiguration setzen
# Tests (Pester 5)
Invoke-Pester -Path .\tests\DocFlowEngine.Tests.ps1
# Debugger: Haltepunkt in einer Teildatei, zum Beispiel
Set-PSBreakpoint -Script .\scripts\DocFlowEngine\CopyForward.ps1 -Line 292
Invoke-DocFlowEngine -ConfigPath .\config\docflow-config.psd1 -DryRun
Die Teildateien werden beim Import per Dot-Sourcing geladen (Common.ps1, Config.ps1, State.ps1, Lock.ps1, Naming.ps1, CopyForward.ps1, CopyBack.ps1). Haltepunkte setzt man daher auf die Teildatei, nicht auf DocFlowEngine.psm1. Nach einer Codeänderung Import-Module … -Force ausführen. Den Ablauf erklärt Implementierungsnotizen und die Modulreferenz. Das Tests-Kapitel steht unter Tests.
Typische Probleme zwischen Konfiguration und anderen Repos
| Symptom | Ursache | Lösung |
|---|---|---|
| Dateien werden zweimal verarbeitet | zwei Rechner mit lokalem stateFile |
gemeinsamen Ordner verwenden (Multi-Machine) |
Whitelist aus dem Repo (config/project-routes.txt) greift nicht |
die Laufzeit-Kopie (projectRoutesFile) wird nur ergänzt, nicht ersetzt |
Abgleich mit projectRoutesSeedFile, siehe Konfiguration |
| Fehler nur im Task Scheduler | Arbeitsverzeichnis anders, relative Pfade laufen ins Leere | absolute Pfade, Arbeitsverzeichnis in der Aufgabe setzen |
| OneDrive liefert Dateien verspätet | Sync noch nicht abgeschlossen | Invoke-OneDriveSync.ps1 vor dem Lauf, siehe Nutzung |