Fehlerbehebung

Etwas in AWR verhält sich nicht so, wie du es erwartest. Dieser Leitfaden arbeitet von Symptomen zu Lösungen: zuerst Gesundheitschecks, dann Datenbankprobleme, dann unterbrochene Änderungen an deinen Quelldateien. Jeder Abschnitt nennt den exakten Befehl und wie man die Ausgabe liest. Für die Alltagsbefehle siehe Täglicher Workflow und CLI-Referenz.

Schritt eins: Gesundheitscheck ausführen

AWR liefert einen eingebauten Diagnosebefehl namens Doctor, auf zwei Ebenen:

awr --json doctor --database-only
awr --json doctor

• --database-only prüft die SQLite-Datenbank selbst: Integrität, Fremdschlüssel, Schemaversion, Migrationsidentitäten und AWR-eigene Schemaobjekte.
• Der vollständige doctor untersucht zusätzlich deine ausgewählten Quelldateien und die Bindungen zwischen Laufzeitdatensätzen und Dateien auf der Festplatte.

Doctor öffnet die Datenbank schreibgeschützt. Es migriert nicht das Schema, reindiziert keine Quellen, wendet keine ausstehenden Mutationen an, lässt keine Claims ablaufen und löscht keine verwaisten Dateien — es ist also immer sicher auszuführen, selbst bei einem beschädigten Projekt.

Doctors Befunde lesen

Doctor meldet Probleme als explizite Befunde statt zu raten:

• schema_issues — fehlende oder geänderte AWR-eigene Tabellen, Spalten, Indizes oder Trigger, geprüft gegen gebündelte Migrationen. Zusätzliche Objekte können koexistieren; Doctor repariert keine Definitionen und gibt ihr SQL nicht aus.
• foreign_key_check_error — eine fehlerhafte Referenz verhinderte, dass SQLite seinen Fremdschlüssel-Check überhaupt ausführen konnte. Wenn du dieses Feld siehst, ist die Datenbank ungesund, und eine gemeldete Null bei Verletzungen bedeutet „wir konnten sie nicht zählen", nicht „alles in Ordnung".
• Aktive Sessions — nur informativ; ein alter Datensatz beweist nicht, dass der Prozess tot ist.
• Fehlende Abhängigkeiten, verwaiste Kanten, nicht verfügbare Quellen, unterbrochene Speichervorgänge und beschädigte oder nicht registrierte Artefakte werden jeweils als Befunde gemeldet. Unlesbare Seiten oder eine fremde (Nicht-AWR-) Datenbank erzeugen explizite Fehler, keinen irreführenden Status.

Symptom: „AWR hat meine Quelldatei abgelehnt"

Wenn eine YAML-Quelldatei einen Syntaxfehler oder ein Feld vom falschen Typ hat, schlägt AWR mit dem Fehlercode InvalidInput und strukturierten Details fehl:

{
  "location": {
    "locator": "file:///project/work.yaml",
    "pointer": "/work_items/0/title",
    "line": 3,
    "column": 10
  },
  "rule": "ledger.string",
  "repair": "Use a quoted string or a YAML block scalar (|) for multiline text."
}

So liest du es: pointer benennt das betroffene Feld mit dem Vokabular deiner eigenen Quelldatei (einschließlich konfigurierter chinesischer Feldnamen); line und column sind einbasiert. Reine Syntaxfehler haben möglicherweise nur Parser-Koordinaten, und manche Lookups (wie YAML-Aliase) behalten den Pointer mit null-Koordinaten — das lehnt eine ansonsten gültige Datei nicht ab. rule benennt die fehlgeschlagene Erwartung; repair beschreibt die erwartete Struktur. Es bearbeitet niemals die Datei und gibt den abgelehnten Wert nicht zurück.

Ein häufiger Fall: Du hast title: [Draft, Review] geschrieben, was YAML als Liste parst, aber das Feld erfordert einen String. Wenn das Komma wörtlich gemeint war:

title: "Draft, Review"

Für mehrzeilige Beschreibungen verwende einen YAML-Block-Scalar (|); gültiger chinesischer Text und Pfade mit Leerzeichen werden vollständig unterstützt.

Symptom: „Meine Änderungen tauchen in Abfragen nicht auf"

Du hast eine Quelldatei bearbeitet, aber AWR zeigt noch alte Fakten. Führe eine Reindizierung aus:

awr source reindex

Prüfe dann beide Teile des Berichts: Operationserfolg und Projektionsvollständigkeit. Ein Scan kann erfolgreich sein, während die Projektion unvollständig bleibt, weil der Scan Quellen beobachtet, ohne ihre geänderten Fakten zu importieren. Derselbe Bericht kommt als JSON mit --json und über MCP awr_source_reindex. Vergleiche Ausgaben von gleichwertigen Ausgangssnapshots; die Reindizierung selbst aktualisiert den Quellenzustand.

Wenn die Nachweise eines Arbeitselements falsch aussehen, meldet work show (oder MCP awr_work_get) evidence_groups neben der flachen evidence-Liste. Jede Gruppe hat einen exakten Locator; eine Quellenreferenz und ein verifizierter Bericht am selben Pfad bleiben getrennt, und die Gruppierung überträgt niemals Verifizierung zwischen Datensätzen.

Symptom: „Die Datenbank ist korrupt oder verloren"

Deine Quelldateien sind maßgeblich für Projektfakten, aber die SQLite-Datenbank (.awr/state.db) enthält auch Zustand, den diese Dateien nicht enthalten: Sessions, Claims, Checkpoints, Laufzeitereignisse, Artefakt-Registrierungen und Mutationsversuche. Reindizierung aktualisiert Projektionen aus den Quellen, aber sie kann diese Laufzeithistorie nicht wiederaufbauen — und eine frische Datenbank aus denselben Quellen zu initialisieren auch nicht.

Richtig sichern

Für einen wiederherstellbaren Snapshot bewahre all das zusammen auf und pausiere Projekt-Schreibprozesse beim Zusammenstellen (SQLites Backup-API liefert ein kohärentes Datenbankabbild, snapshotet aber nicht die umgebenden Dateien):

• Ein kohärentes Backup von .awr/state.db, erstellt mit SQLites Backup-API oder gleichwertigem Tooling — die Datei zu kopieren, während Schreibprozesse aktiv sind, kann committete Datensätze verpassen, die noch im Write-Ahead-Log sind.
• Die passenden Quelldateien, die Git-Revision, .awr/project.toml, die Authorized-Root- Konfiguration und alle explizit autorisierten externen Quellen.
• Verwaltete Artefaktdateien, registrierte lokale Artefakte außerhalb des verwalteten Verzeichnisses und die .awr/mutations-Wiederherstellungsjournale und -Snapshots, auf die ausstehende Operationen verweisen.

Wiederherstellen

1. Stoppe das Projekt.
2. Stelle am aufgezeichneten kanonischen Stamm wieder her; behalte den verdrängten Zustand statt ihn zu löschen.
3. Führe awr --json doctor --database-only aus, dann den vollständigen awr --json doctor.

Eine Wiederherstellung kann eine Artefakt-Registrierung wiederherstellen, während ihre Datei noch fehlt — stelle die Datei wieder her oder lass den Befund unaufgelöst. awr source reindex ist weder ein Laufzeit-Restore noch ein Datenbank-Umzugswerkzeug.

Doctor kann benannte Reparaturen durchführen, aber nur mit der aktuellen Projektrevision, einem ausgewählten Objekt und einer Begründung; Reparaturen bewahren Quellen und nicht betroffenen Laufzeitzustand. Wenn die Datenbankintegrität beschädigt ist, sind vorgeschlagene Laufzeit-Reparaturen deaktiviert — keine automatische Rekonstruktion.

Symptom: „Eine Mutation wurde mitten im Schreibvorgang unterbrochen"

AWR wendet genehmigte Vorschläge mit Dauerhaftigkeitsgarantien auf deine Quelldateien an: Unveränderliche Vorher/Nachher-Snapshots werden gespeichert, bevor der Versuch aufgezeichnet wird, und Erfolg erfordert die beabsichtigten Quellbytes, eine neu gebaute Projektion und das finale Anwendungsereignis. Wenn ein Prozess mitten im Schreibvorgang stirbt, bleibt der Versuch offen und wiederherstellbar.

Wenn du MutationIncomplete mit write_outcome: pending_recovery erhältst, untersuche zuerst:

awr --json doctor
awr --json proposal show PROPOSAL_ID

Lies die aktuelle project_revision aus der Ausgabe und setze dann den Vorschlag fort:

awr --json proposal recover PROPOSAL_ID \
  --actor reviewer \
  --reason "Resume the interrupted report review" \
  --expected-revision CURRENT_REVISION

Was die Wiederherstellung tut, hängt davon ab, wie weit der Versuch gekommen ist:

Ein erfolgreicher erneuter Versuch meldet recovered, nennt den ursprünglichen Versuch und bindet seine resolved_event_id an das finale Ereignis.

Zwei Dinge, die du nicht tun solltest:

• Bearbeite die Snapshots nicht, um ein Ergebnis zu erzwingen. Wenn die aktuelle Quelle zu keinem der Snapshots passt, löse den Quellenkonflikt und bereite einen neuen Vorschlag vor.
• Nimm nicht an, dass ein erneuter Versuch die Datei geschrieben hat. source_write_performed beschreibt nur den aktuellen Aufruf — weshalb die Wiederherstellung zuerst revalidiert.

Nebenläufigkeit: AWR-Schreibprozesse koordinieren über eine quellbezogene OS-Sperre und transaktionale expected_revision-Prüfungen. Getrennte Quellen schreiten unabhängig fort, aber eine dazwischenliegende Projektrevision kann einen expliziten Wiederherstellungsversuch erfordern. Externe Editoren nehmen nicht an der Sperre teil; Fingerabdruckprüfungen erkennen ihre Änderungen.

Wann du stoppen und um Hilfe bitten solltest

Stoppe und eskaliere statt zu improvisieren, wenn:

• Doctor beschädigte Datenbankintegrität meldet (foreign_key_check_error, unlesbare Seiten) — Laufzeit-Reparaturen sind deaktiviert, ohne automatische Rekonstruktion.
• Eine Mutationswiederherstellung einen Quellen-/Snapshot-Konflikt meldet — der unterstützte Weg ist ein neuer Vorschlag, nicht das manuelle Bearbeiten von Snapshots oder Journalen.
• Dein Szenario Stromausfall der Maschine, verteilte Schreibprozesse oder andere Betriebssysteme betrifft — die Wiederherstellungsgarantien decken lokale Prozessunterbrechung ab; darüber hinaus ist nichts festgelegt.

Bevor du um Hilfe bittest oder ein Issue einreichst, halte den Zustand fest, solange er frisch ist:

awr --json doctor --database-only
awr --json doctor
awr --json proposal show PROPOSAL_ID   # if a mutation is involved

Bewahre die verdrängte Datenbank, die .awr/mutations-Journale und die relevanten Quelldateien unangetastet — sie machen einen Bericht umsetzbar, und sie sind deine Absicherung, wenn die Lösung schiefgeht.