Dépannage

Quelque chose dans AWR ne se comporte pas comme prévu. Ce guide part des symptômes vers les corrections : d'abord les vérifications de santé, puis les problèmes de base de données, puis les changements interrompus de vos fichiers sources. Chaque section donne la commande exacte à exécuter et comment lire la sortie. Pour les commandes du quotidien, voir Flux de travail quotidien et Référence CLI.

Première étape : lancez une vérification de santé

AWR embarque une commande de diagnostic intégrée appelée Doctor, à deux niveaux :

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

• --database-only vérifie la base SQLite elle-même : intégrité, clés étrangères, version du schéma, identités des migrations et objets de schéma appartenant à AWR.
• Le doctor complet inspecte en plus vos fichiers sources sélectionnés et les liaisons entre les enregistrements runtime et les fichiers sur le disque.

Doctor ouvre la base en lecture seule. Il ne migre pas le schéma, ne réindexe pas les sources, n'applique pas les mutations en attente, ne fait pas expirer les réservations et ne supprime pas les fichiers orphelins — il est donc toujours sûr à exécuter, même sur un projet endommagé.

Lire les constatations de Doctor

Doctor rapporte les problèmes sous forme de constatations explicites plutôt que de deviner :

• schema_issues — tables, colonnes, index ou déclencheurs appartenant à AWR manquants ou modifiés, vérifiés contre les migrations embarquées. Des objets supplémentaires peuvent coexister ; Doctor ne réparera pas les définitions et n'affichera pas leur SQL.
• foreign_key_check_error — une référence malformée a empêché SQLite de simplement exécuter son contrôle de clés étrangères. Si vous voyez ce champ, la base est malade, et un zéro violation rapporté signifie « nous n'avons pas pu les compter », pas « tout va bien ».
• Sessions actives — informatif seulement ; un vieil enregistrement ne prouve pas que le processus est mort.
• Dépendances manquantes, arêtes pendantes, sources indisponibles, enregistrements interrompus et artefacts endommagés ou non enregistrés sont chacun rapportés comme des constatations. Des pages illisibles ou une base étrangère (non AWR) produisent des erreurs explicites, pas un statut trompeur.

Symptôme : « AWR a rejeté mon fichier source »

Quand un fichier source YAML a une erreur de syntaxe ou un champ du mauvais type, AWR échoue avec le code d'erreur InvalidInput et des détails structurés :

{
  "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."
}

Comment le lire : pointer nomme le champ fautif en utilisant le vocabulaire propre de votre fichier source (y compris les noms de champs chinois configurés) ; line et column commencent à un. Les erreurs de syntaxe pures peuvent n'avoir que des coordonnées d'analyseur, et certaines recherches (comme les alias YAML) gardent le pointeur avec des coordonnées nulles — cela ne rejette pas un fichier par ailleurs valide. rule nomme l'attente non satisfaite ; repair décrit la structure attendue. Il n'édite jamais le fichier ni ne répercute la valeur rejetée.

Un cas fréquent : vous avez écrit title: [Draft, Review], que YAML analyse comme une liste, alors que le champ exige une chaîne. Si la virgule était voulue littéralement :

title: "Draft, Review"

Pour les descriptions multilignes, utilisez un scalaire de bloc YAML (|) ; le texte chinois valide et les chemins avec espaces sont entièrement pris en charge.

Symptôme : « Mes modifications n'apparaissent pas dans les requêtes »

Vous avez édité un fichier source mais AWR affiche encore d'anciens faits. Lancez une réindexation :

awr source reindex

Puis vérifiez les deux parties du rapport : le succès de l'opération et la complétude de la projection. Un balayage peut réussir alors que la projection reste incomplète, parce que le balayage observe les sources sans importer leurs faits modifiés. Le même rapport est disponible en JSON avec --json et via MCP awr_source_reindex. Comparez les sorties à partir d'instantanés de départ équivalents ; la réindexation elle-même met à jour l'état des sources.

Si les preuves d'un élément de travail semblent incorrectes, work show (ou MCP awr_work_get) rapporte evidence_groups à côté de la liste plate evidence. Chaque groupe a un localisateur exact ; une référence source et un rapport vérifié au même chemin restent distincts, et le regroupement ne transfère jamais la vérification entre enregistrements.

Symptôme : « La base de données est corrompue ou perdue »

Vos fichiers sources font autorité pour les faits du projet, mais la base SQLite (.awr/state.db) contient aussi un état que ces fichiers ne contiennent pas : sessions, réservations, points de contrôle, événements runtime, enregistrements d'artefacts et tentatives de mutation. La réindexation rafraîchit les projections depuis les sources, mais elle ne peut pas reconstruire cet historique runtime — et initialiser une base neuve depuis les mêmes sources ne le peut pas non plus.

Sauvegarder correctement

Pour un instantané récupérable, conservez tout ceci ensemble, et mettez en pause les processus écrivant dans le projet pendant que vous l'assemblez (l'API de sauvegarde de SQLite donne une image cohérente de la base, mais ne capture pas les fichiers environnants) :

• Une sauvegarde cohérente de .awr/state.db réalisée avec l'API de sauvegarde de SQLite ou un outillage équivalent — copier le fichier pendant que des écrivains sont actifs peut manquer des enregistrements validés encore dans le journal write-ahead.
• Les fichiers sources correspondants, la révision Git, .awr/project.toml, la configuration de racine autorisée et toutes les sources externes explicitement autorisées.
• Les fichiers d'artefacts gérés, les artefacts locaux enregistrés hors du répertoire géré, et les journaux de reprise et instantanés .awr/mutations référencés par des opérations en attente.

Restaurer

1. Arrêtez le projet.
2. Restaurez à la racine canonique enregistrée ; conservez l'état déplacé au lieu de le supprimer.
3. Exécutez awr --json doctor --database-only, puis le awr --json doctor complet.

Une restauration peut récupérer un enregistrement d'artefact alors que son fichier est encore manquant — restaurez le fichier ou laissez la constatation non résolue. awr source reindex n'est ni un outil de restauration runtime ni un outil de relocalisation de base.

Doctor peut effectuer des réparations nommées, mais seulement avec la révision courante du projet, un objet sélectionné et une raison ; les réparations préservent les sources et l'état runtime sans rapport. Si l'intégrité de la base est rompue, les réparations runtime suggérées sont désactivées — aucune reconstruction automatique.

Symptôme : « Une mutation a été interrompue en pleine écriture »

AWR applique les propositions approuvées à vos fichiers sources avec des garde-fous de durabilité : des instantanés immuables avant/après sont enregistrés avant que la tentative ne soit consignée, et le succès exige les octets sources visés, une projection reconstruite et l'événement final d'application. Si un processus meurt en pleine écriture, la tentative reste ouverte et récupérable.

Si vous obtenez MutationIncomplete avec write_outcome: pending_recovery, inspectez d'abord :

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

Lisez la project_revision courante dans la sortie, puis reprenez la proposition :

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

Ce que fait la reprise dépend de l'avancement de la tentative :

Une nouvelle tentative réussie rapporte recovered, nomme la tentative originale et lie son resolved_event_id à l'événement final.

Deux choses à ne pas faire :

• Ne modifiez pas les instantanés pour forcer un résultat. Si la source courante ne correspond à aucun des deux instantanés, résolvez le conflit de source et préparez une nouvelle proposition.
• Ne présumez pas qu'une nouvelle tentative a écrit le fichier. source_write_performed ne décrit que l'invocation courante — c'est pourquoi la reprise revalide d'abord.

Concurrence : les écrivains AWR se coordonnent via un verrou OS par source et des contrôles transactionnels d'expected_revision. Des sources séparées progressent indépendamment, mais une révision de projet intervenue entre-temps peut exiger une nouvelle tentative de reprise explicite. Les éditeurs externes ne rejoignent pas le verrou ; les contrôles d'empreintes détectent leurs modifications.

Quand s'arrêter et demander de l'aide

Arrêtez-vous et escaladez au lieu d'improviser quand :

• Doctor rapporte une intégrité de base rompue (foreign_key_check_error, pages illisibles) — les réparations runtime sont désactivées, sans reconstruction automatique.
• Une reprise de mutation rapporte un conflit source/instantané — le chemin pris en charge est une nouvelle proposition, pas l'édition manuelle des instantanés ou des journaux.
• Votre scénario implique une coupure de courant de la machine, des écrivains distribués ou d'autres systèmes d'exploitation — les garanties de reprise couvrent l'interruption d'un processus local ; au-delà, rien n'est établi.

Avant de demander de l'aide ou de déposer un ticket, capturez l'état tant qu'il est frais :

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

Gardez la base déplacée, les journaux .awr/mutations et les fichiers sources concernés intacts — ils rendent un rapport exploitable, et ils sont votre recours si la correction tourne mal.