Dépannage¶

Symptômes fréquents¶

Symptôme	Cause probable	Que faire
Le navigateur n'ouvre pas l'application, ou boucle vers le nom du site	Pas de certificat HTTPS. nginx redirige tout en HTTPS et ne relaie pas l'API en HTTP.	Suivre HTTPS.
Le micro est refusé	Contexte non sécurisé.	Idem.
`docker compose ps` montre le backend `unhealthy` au démarrage	Il attend Whisper et Ollama. Le premier chargement de large-v3 peut dépasser deux minutes, le téléchargement du modèle Ollama jusqu'à une heure.	Attendre, suivre `docker compose logs -f ollama`.
Log Ollama `failed to pull`	Nom de modèle inexistant, DNS ou réseau. Ollama reste démarré mais le backend échouera.	Vérifier `OLLAMA_MODEL` et la connexion.
`docker compose build` échoue en ne résolvant aucun nom, ou Ollama ne télécharge pas son modèle, alors que l'hôte a bien Internet	Le routage IPv4 de l'hôte est coupé : aucun conteneur ne peut sortir. Vérifier avec `cat /proc/sys/net/ipv4/ip_forward`, qui doit valoir 1. Docker le pose au démarrage, mais une coupure réseau ou un rechargement de `sysctl` peut le remettre à 0.	`sudo sysctl -w net.ipv4.ip_forward=1`, puis le rendre durable avec un fichier dans `/etc/sysctl.d/`. Les conteneurs déjà démarrés paraissent sains, car ils ne font que répondre à des connexions entrantes.
Rapport en erreur « Délai dépassé en attente de la transcription des segments »	Les segments n'ont pas été transcrits dans le délai, dix minutes par défaut. Whisper est saturé ou arrêté.	Vérifier Whisper, relancer la génération depuis la consultation.
Rapport en erreur « Aucune dictée enregistrée » ou « Aucun enregistrement audio »	Génération demandée sur une piste sans audio.	Le médecin doit d'abord enregistrer.
Rapport en erreur « La rédaction a été interrompue avant d'aboutir »	Le serveur s'est arrêté pendant la rédaction, ou le worker est mort. La file vit en mémoire, donc personne ne reprend le travail.	Rien à réparer : le médecin relance la génération, ses enregistrements sont intacts.
Un rapport reste indéfiniment « en cours de génération »	Ne devrait plus arriver : un balayage toutes les minutes clôt les rédactions sans tâche pour les finir. Si cela persiste, une tâche est bien vivante mais bloquée.	Regarder les logs du backend et d'Ollama, puis `docker compose restart backend` : au redémarrage la rédaction est close en erreur et relançable.
Disque plein, ou avertissement « Le dossier audio occupe N Go »	Les audios ne sont plus purgés depuis le 10/10/2026.	Voir Exploitation. Archiver ou supprimer les plus anciens fichiers de `~/.cause/audio/`, qui ne sont plus nécessaires au fonctionnement.
Message « Cette consultation est en cours d'enregistrement par un autre médecin »	Verrou de visibilité, trente minutes après la dernière activité.	Attendre l'expiration, ou faire terminer l'enregistrement par son initiateur.
Message « Accès refusé : rôle … non autorisé »	Fonction d'administration appelée par un compte non ADMIN.	Utiliser un compte ADMIN.
Une consultation, un patient ou un compte a disparu après une restauration	Son fichier dans `~/.cause/` est vide, tronqué ou sans identifiant. Le serveur démarre quand même et l'ignore.	Chercher dans les logs `ignoré au démarrage`, qui nomme le fichier fautif. Le restaurer depuis une sauvegarde.
Plus aucun type d'acte n'est proposé	Le dossier `~/.cause/act-types/` ne contient que des fichiers inexploitables. Le catalogue par défaut n'est réinstallé que si le dossier est vide.	Vider le dossier, puis redémarrer le backend : le catalogue livré est réécrit.
Le mot de passe admin est introuvable dans les logs	Un compte ADMIN existait déjà au démarrage.	Réinitialiser depuis un autre compte ADMIN.
Une mise à jour ne change rien au comportement du serveur, par exemple un écran de licence qui refuse toujours	Le conteneur tourne encore sur l'ancienne image. `docker compose build` produit bien une nouvelle image, mais `docker compose restart` ne fait que redémarrer le conteneur existant, qui reste attaché à celle avec laquelle il a été créé. `docker compose ps` le trahit : la colonne `IMAGE` affiche un identifiant `sha256:...` au lieu du nom de l'image.	`docker compose up -d <service>`, qui recrée le conteneur dès que l'image attendue a changé. `restart` ne suffit que pour ce qui est lu hors du programme : un fichier de `~/.cause/`, un certificat, une variable d'environnement.
Aucun manuel dans l'application, et le chatbot documentaire ne répond rien	L'image du backend a été construite sans les manuels. Le log de démarrage porte « Manuel ... absent du jar ».	Reconstruire avec `docker compose build backend` depuis la racine du dépôt, le contexte devant inclure `docs/manuel`.
403 sur les QR codes	Droits sur le dossier `qrcodes`.	Relancer le script, puis `docker compose restart frontend`.
L'installation signale « manque » ou « taille différente » sur un fichier du disque	Le fichier n'a pas la taille que `TAILLES.txt` déclare : copie interrompue, disque débranché, ou fichier modifié depuis la préparation.	L'installation continue, c'est à vous de juger. S'il s'agit d'un blob de modèle, son nom est son propre condensé : `sha256sum <fichier>` tranche. Si le fichier est bien abîmé, refaire préparer le disque, puis relancer le script, qui ne touche à aucune donnée du serveur.
L'installation s'arrête au moment de tirer les images, ou `docker compose pull` répond `denied`	Le backend et le frontend sont des paquets privés : jeton de lecture absent, expiré ou sans le droit `read:packages`, pas de réseau, ou version absente du registre.	Reposer le jeton dans `~/.cause/.env.ghcr`, voir Le jeton du registre, ou se connecter à la main par `sudo docker login ghcr.io`. La version attendue est la ligne `CAUSE_VERSION` de `~/.cause/.env`, et le bloc `images:` de `VERSION`, sur le disque, nomme ce qui doit être tiré.
Au démarrage, « No such image: cause-whisper:... » ou la même chose pour `cause-ollama` ou `cause-qwen-asr`	Les trois moteurs ne viennent d'aucun registre : leur image est chargée depuis le disque de livraison, et rien ne la retélécharge. Soit le chargement n'a pas eu lieu, soit la ligne `CAUSE_MOTEURS` de `~/.cause/.env` ne désigne pas l'image que la machine a reçue.	`docker image ls \\| grep cause-` pour voir ce qui est chargé, puis relancer le script du disque. Le bloc `moteurs:` de `VERSION` nomme les étiquettes attendues. À la main : `docker load -i images/cause-whisper.tar` charge l'archive, qui ne porte pas la version, puis `docker tag cause-whisper:disque cause-whisper:<version>` pose celle que le compose désigne.
Bandeau rouge « Licence refusée, arrêt dans ... »	La licence est refusée, mais la fenêtre de soixante-douze heures court encore : tout fonctionne normalement.	Appelez l'éditeur maintenant, avec les trois lignes d'empreinte. Voir La licence machine. La fenêtre ne se renouvelle pas.
Écran « Kauze ne peut pas démarrer sur cette machine »	Licence absente, modifiée, ou émise pour un autre serveur, et la fenêtre de soixante-douze heures est écoulée ou n'a pas été accordée.	Suivre les trois questions de La licence machine. Les données ne sont pas touchées.
Arrêt immédiat, l'écran disant qu'aucune fenêtre n'a été accordée	Le compteur `~/.cause/licence-grace.txt` est absent ou a été modifié. Un nettoyage du dossier `~/.cause` ou un fichier réécrit à la main en sont les causes habituelles ; une restauration, elle, le ramène.	Corriger la cause du refus nommée à l'écran, ou demander une nouvelle licence. Le compteur se reconstruit seul une fois la licence acceptée ; ne pas l'écrire à la main, un fichier non scellé bloque.
Écran « Kauze ne sait pas sur quelle machine il tourne »	Les fichiers d'identité ne sont pas lisibles dans le conteneur : montage manquant dans `docker-compose.yml`. Défaut d'installation, pas de licence.	L'écran nomme chaque source et son chemin. Rétablir les montages, `docker compose up -d`.
Bandeau « Licence de maintenance échue »	Redevance annuelle arrivée à échéance.	Rien n'est bridé, le logiciel fonctionne. Contacter l'éditeur.
« Permission denied » en modifiant `~/.cause/.env`	Installation posée avant la 1.0.15 : le script tournait en root et les deux fichiers de configuration lui appartenaient, alors que les mises à jour se font sans `sudo`.	`sudo chown $USER:$USER ~/.cause/.env ~/.cause/.env.backend ~/.cause/.env.backend.overrides ~/.cause/docker-compose.yml`, une fois pour toutes. Les installations suivantes les rendent elles-mêmes à votre compte.
Un réglage a disparu, l'application est revenue à son comportement par défaut	Le réglage était écrit dans `~/.cause/.env.backend`, que le script réécrit entièrement à chaque passage : une mise à jour ou une réparation l'a effacé sans rien dire.	Réécrire le réglage dans `~/.cause/.env.backend.overrides`, qui n'est jamais réécrit, puis `cd ~/.cause && docker compose up -d backend`. Voir Votre fichier de réglages.
Un réglage écrit dans le fichier de réglages ne fait rien	Le backend n'a pas été redémarré, ou la ligne porte des espaces autour du signe égal ou des guillemets, ou la valeur est fixée par le docker-compose.	`cd ~/.cause && docker compose exec backend printenv <NOM>` dit ce que le conteneur voit vraiment. La liste des valeurs que le compose impose est dans Ce que ce fichier ne change pas.

GPU¶

Mémo établi sur la machine de référence : RTX 5060 Ti 16 Go, Ubuntu 24.04, noyau HWE.

Le pilote ne voit plus la carte¶

nvidia-smi répond « No devices were found » et dmesg contient RmInitAdapter failed. Deux causes :

Mauvais module. Cette génération de cartes n'accepte que le module NVIDIA ouvert. Le pilote fermé, dont le nvidia-driver-550 posé par le script d'installation, échoue sans message clair. Vérifiez avec modinfo nvidia | grep license, qui doit répondre Dual MIT/GPL.
Noyau mis à jour sans module. Avec des modules précompilés, chaque nouveau noyau arrive sans le module NVIDIA dès lors que les paquets du pilote sont gelés, comme le recommande la section suivante. apt-mark showhold dit s'ils le sont. Restauration immédiate :

bash sudo apt install linux-modules-nvidia-595-open-$(uname -r) sudo modprobe nvidia

Le pilote et ses bibliothèques ne sont plus d'accord¶

nvidia-smi répond Failed to initialize NVML: Driver/library version mismatch, et un conteneur refuse de démarrer sur failed to fulfil mount request: open /run/nvidia-persistenced/socket. Symptôme différent du précédent : la carte est là, mais l'espace utilisateur a avancé sans le module.

Une mise à jour du canal de sécurité a installé une nouvelle version du pilote. Les paquets gelés par le script d'installation ne couvrent que les modules (linux-modules-nvidia-595-*), pas les bibliothèques (libnvidia-gl-595, nvidia-compute-utils-595, libnvidia-cfg1-595). Le module chargé reste celui du dernier démarrage, et rien ne rattrape l'écart sans redémarrage.

Comparez les deux versions pour confirmer :

cat /proc/driver/nvidia/version            # version du module chargé
nvidia-smi 2>&1 | grep 'NVML library'      # version des bibliothèques
grep -i nvidia /var/log/dpkg.log | grep upgrade

Restauration : redémarrer. Le module est rechargé dans la version des bibliothèques. Les conteneurs déjà démarrés continuent de fonctionner jusque-là, parce qu'ils tiennent ouverts des descripteurs sur l'ancien pilote ; ce sont les nouveaux conteneurs qui échouent, ce qui rend la panne trompeuse.

Pour éviter la récidive, geler toute la pile du pilote et non ses seuls modules :

sudo apt-mark hold $(dpkg-query -W -f='${Package}\n' | grep -E '^(lib)?nvidia|^xserver-xorg-video-nvidia')

Sur un serveur livré, c'est obligatoire : sans cela, une seule mise à jour du pilote suffit à arrêter la transcription et la rédaction, sans qu'aucun écran de l'application n'en dise la cause. Le gel n'est que la seconde ligne de défense : les mises à jour automatiques sont coupées, et une installation se termine par un redémarrage et une vérification, voir Mises à jour du système.

Solution durable : DKMS¶

Le paquet nvidia-dkms-595-open recompile le module à chaque changement de noyau. Il exige les en-têtes du noyau HWE et le Secure Boot désactivé. L'ordre est impératif :

retirer les paquets précompilés ;
installer nvidia-dkms-595-open ;
vérifier que ls /lib/modules/$(uname -r)/updates/dkms/ contient le module ;
redémarrer seulement après cette vérification.

Gelez ensuite les paquets du pilote fermé avec apt-mark hold pour qu'une mise à jour ne les réinstalle pas.

Réflexe de diagnostic¶

uname -r
apt-mark showhold
dkms status
modinfo nvidia | grep license
nvidia-smi

Pas de redémarrage automatique¶

Ni les mises à jour ni le redémarrage qu'elles exigent ne se font d'eux-mêmes : les minuteurs apt-daily sont masqués et unattended-upgrades est hors service. Un redémarrage se décide dans une fenêtre de maintenance, voir Mises à jour du système.