Troubleshooting¶
Diagnostic de premier niveau¶
Avant toute investigation, lancer ces trois commandes dans l'ordre :
# 1. Confirme que le script est accessible et exécutable
bash hash-tool version
# 2. État de toutes les dépendances + mode d'exécution actif
bash hash-tool check-env
# 3. Inspecte le préfixe des chemins dans la base concernée
head -3 <fichier.b3>
La sortie de check-env identifie immédiatement les composants manquants ou défaillants.
Le préfixe des chemins dans le .b3 révèle les problèmes de répertoire de travail.
Convention¶
Chaque problème suit le format :
Symptôme → ce qui est observable
Cause → pourquoi cela se produit
Diagnostic → commande à lancer pour confirmer
Solution → correctif à appliquer
Tableau symptôme → page¶
| Symptôme | Page |
|---|---|
b3sum introuvable, hash-tool non exécutable |
Installation |
bash version insuffisante, erreurs de syntaxe au démarrage |
Installation |
| Image Docker absente, fallback non déclenché | Installation |
Exit 126 en CI (integrity.sh non exécutable) |
Installation |
verify échoue sur tous les fichiers malgré données intactes |
Exécution |
.b3 vide ou nombre de fichiers anormal |
Exécution |
compare retourne des milliers de modifiés inattendus |
Exécution |
verify retourne exit 1 alors que la sortie affiche OK |
Exécution |
Fichiers .b3 non créés sur l'hôte après compute Docker |
Docker |
| Exécution Docker très lente sur WSL2 | Docker |
Permission denied sur /bases ou /resultats |
Docker |
exec format error sur ARM64 / NAS Synology |
Docker |
Chemins /mnt/c/ non montés correctement |
Docker |
| Pipeline JSON : erreur jq, parse error | Pipeline |
Champ op / type non reconnu |
Pipeline |
| Pipeline s'arrête à mi-exécution | Pipeline |
| Chemins relatifs non résolus dans le pipeline | Pipeline |
report.html absent ou vide |
Résultats |
RESULTATS_DIR ignoré, résultats écrits ailleurs |
Résultats |
| Résultats écrasés à chaque exécution | Résultats |
failed.txt absent malgré exit 1 |
Résultats |
Ouvrir une issue GitHub¶
Inclure systématiquement :
- Sortie de
bash hash-tool version - Sortie de
bash hash-tool check-env - Commande exacte lancée
- Sortie complète (avec
bash -x hash-tool <commande>pour le mode trace) - OS et version (
uname -a)