Dépannage

Symptômes ci-dessous, dans l'ordre ; recherchez le vôtre sur la page. Os { NotFound } depuis herdr plugin · update indique "not currently on a branch" · tailscale serve failed · ne répond pas (le service ne démarre pas) · le téléphone ne peut pas ouvrir l'URL · la page se charge mais reste vide (page blanche, 403) · une invite de mot de passe n'accepte pas votre saisie · aucune notification push · disparu après un redémarrage · un panneau reste étroit · Collie refuse d'ouvrir une fenêtre tmux · tmux list: output did not parse · herdr plugin list affiche l'ancienne version · interface obsolète après une recompilation · j'ai enregistré une machine dans Herdr et le téléphone ne l'affiche pas · une mise à jour lancée depuis le téléphone reste en attente.

herdr plugin … échoue avec Error: Os { code: 2, kind: NotFound, message: "No such file or directory" } (échec de l'installation du plugin, échec de l'appel d'action). Ce n'est pas un problème Collie : le serveur Herdr n'est pas lancé, donc son CLI ne peut pas joindre le socket de contrôle (~/.config/herdr/herdr.sock). L'indice est l'erreur brute Os {…} : un serveur joignable répond aux problèmes de chemin ou de manifeste par du JSON structuré (ex. plugin_manifest_not_found), donc un simple Os { NotFound } indique un échec de connexion au socket, avant même que Collie ou votre chemin ne soient examinés. Cela touche link, install, action invoke (toutes les sous-commandes qui communiquent avec le serveur), tandis que herdr plugin --help fonctionne toujours (il n'ouvre jamais le socket). Solution : démarrez d'abord Herdr (herdr server &, ou lancez simplement le TUI Herdr qui initialise le serveur), confirmez que ls ~/.config/herdr/herdr.sock existe, puis réessayez l'installation. herdr plugin list est un test rapide : s'il renvoie la même erreur, le serveur est arrêté.

update échoue avec You are not currently on a branch. Une installation GitHub effectuée avant 0.23.1 (#63) : herdr plugin install détache au lieu de cloner, donc l'ancien update n'avait aucune branche vers laquelle faire git pull. Le correctif est inclus dans le dépôt qu'il répare ; il faut donc une réinstallation pour l'appliquer : Si cela échoue avec "You are not currently on a branch" contient les trois commandes.

start affiche note: tailscale serve failed. Collie fonctionne correctement (toujours actif sur 127.0.0.1) : seul l'accès tailnet ne s'est pas lancé, et l'erreur de tailscale s'affiche sur le terminal au-dessus de la note. Causes courantes : votre utilisateur n'est pas l'opérateur Tailscale (sudo tailscale set --operator=$USER), le nœud est déconnecté (tailscale up), ou, sur les domaines tailnet Headscale / .internal, les certificats HTTPS ne sont pas disponibles. C'est précisément l'objet de COLLIE_SERVE_MODE=http : définissez-le dans .env, puis lancez bin/collie restart. Vérifiez avec tailscale serve status.

serve indique HTTPS certificates are not enabled on this tailnet. Rien n'a été publié et rien n'est en attente. Ouvrez la console d'administration, activez « Enable HTTPS », puis réexécutez collie serve. Sur les domaines Headscale / .internal, aucun certificat ne peut être activé ; utilisez plutôt COLLIE_SERVE_MODE=http.

La bannière affiche ⚠ Collie isn't answering on :8787 yet (le service ne démarre pas, connexion refusée). Le service a démarré mais le serveur HTTP ne répond pas au test. Vérifiez d'abord l'unité (systemctl --user status collie), puis bin/collie logs (ou journalctl --user -u collie -f pour suivre en direct) pour en trouver la cause : le plus souvent, le port est déjà utilisé (définissez COLLIE_PORT dans .env, puis lancez bin/collie restart, qui réexécute aussi tailscale serve sur le nouveau port) ou la première compilation a échoué (indiqué dans les logs ; corrigez et lancez bin/collie build). L'unité redémarre automatiquement toutes les 5 s ; une fois la cause corrigée, elle revient généralement d'elle-même.

Le téléphone ne peut pas ouvrir l'URL du tailnet. Vérifiez les points suivants dans l'ordre : (1) le téléphone exécute l'application Tailscale et est connecté au même tailnet que l'hôte ; (2) vous ouvrez l'URL tailnet de la bannière (bin/collie url), pas celle en local (http://127.0.0.1:8787 ne fonctionne que sur l'hôte lui-même) ; (3) MagicDNS est activé dans les paramètres DNS de votre tailnet (l'URL est un nom MagicDNS) ; (4) l'hôte est en ligne (vérifiez tailscale status sur l'hôte, ou envoyez un ping à l'hôte depuis l'application Tailscale du téléphone) ; (5) votre politique de tailnet autorise effectivement un pair vers ce nœud : si ce n'est pas le cas, la bannière l'indique désormais sous la ligne tailnet, et rien d'autre ne le fera : le point d'entrée est correctement publié, le certificat est valide, et curl depuis l'hôte lui-même renvoie 200, car le trafic local ne traverse jamais le filtre de paquets. Deux éléments rendent ce cas particulièrement trompeur : tailscale ping réussit (les pings disco contournent les ACL), et le trafic bloqué est abandonné plutôt que refusé, de sorte que le téléphone reste en attente et affiche un serveur hors ligne. Corrigez cela dans votre politique d'ACL (<https://login.tailscale.com/admin/acls> sur Tailscale ; votre fichier de politique sur Headscale). Cette vérification relève du meilleur effort et reste prudente : elle n'alerte que si le filtre de ce nœud n'autorise rien (ce qui peut aussi signifier qu'aucun autre appareil n'a encore rejoint le tailnet) et ne signale rien lorsqu'elle ne peut pas déterminer la situation.

La page se charge mais reste vide (page blanche, écran blanc) ; Les appels API échouent 403 cross-origin rejected. Vous accédez à Collie via une origine non prévue : un domaine personnalisé, ou un proxy qui réécrit Host. Autorisez l'origine publique exacte avec COLLIE_ALLOWED_ORIGINS (voir Configurer), ou configurez le proxy pour qu'il transmette Host sans modification (quatrième exigence pour le proxy dans docs/deployment.md).

Une invite sudo (ou phrase secrète SSH, ou gpg) n'accepte pas votre réponse. Utilisez Saisir dans la ligne Contrôles, pas Envoyer. Envoyer vérifie ce qu'il a saisi en le relisant à l'écran avant d'appuyer sur Entrée (#34), et une invite de mot de passe désactive l'écho, il n'y a donc rien à relire. Saisir envoie directement vos frappes au panneau, Entrée comprise. Rien de ce que vous tapez dans Saisir n'est stocké, reproduit dans un brouillon ou restauré plus tard, et dès que Collie reconnaît une invite de mot de passe, il supprime également le brouillon enregistré (#103).

Aucune notification push n'arrive. Déclenchez-en une manuellement : bin/collie push-test. Trois causes possibles, dans l'ordre où la commande les distingue : push indique être désactivé (les clés n'ont jamais atteint le bridge ; exécutez push-keys et redémarrez, voir Web Push) ; il signale qu'aucun appareil n'est abonné (ce téléphone ne les a jamais activées dans Paramètres → notifications) ; ou il confirme un envoi mais rien n'arrive (le téléphone utilise une origine en simple HTTP, ce qui n'est pas un contexte sécurisé ; Paramètres le signale insecure).

Collie a disparu après un redémarrage. Sur Linux, il s'agit presque toujours de lingering : exécutez loginctl enable-linger $USER (Persistance aux redémarrages). Sur macOS, l'agent launchd démarre au login ; vérifiez donc que vous êtes bien connecté (pas sur l'écran d'ouverture de session) et que l'agent est chargé : launchctl print gui/$(id -u)/herdr.collie.

Le terminal d'un panneau reste étroit, et une application plein écran y est écrasée (Copilot CLI, top, toute TUI dessinée dans une bande étroite pendant que le reste de la copie reste vide). Le terminal du panneau est simplement étroit, et Collie le reproduit fidèlement. La largeur d'un panneau Herdr provient de son rectangle dans la grille de découpe de l'onglet ; un panneau partageant un onglet obtient une part des colonnes. Herdr applique la géométrie du panneau uniquement lorsqu'un client desktop est connecté (herdr#1709) : sans client connecté, fermer une découpe laisse le panneau restant bloqué à l'ancienne largeur étroite, et pane.zoom ainsi que pane.resize via le socket ne le modifient pas non plus. Collie ne peut pas corriger cela de son côté ; il n'écrit pas du tout la géométrie du panneau (ADR 0031 : le téléphone ne redimensionne le terminal de l'opérateur qu'au toucher sur Afficher dans le terminal). Rien de tout cela n'est propre à l'application : top dans un panneau de 54 colonnes donne le même résultat. Pour le mesurer, exécutez tput cols dans le panneau. C'est la largeur réelle, qui peut différer de celle signalée par herdr pane layout. Pour corriger cela, connectez un client Herdr, puis zoomez ou redimensionnez le panneau à cet endroit (herdr pane zoom <pane-id> --on déplace le terminal une fois un client connecté), ou fermez le panneau et ouvrez-en un nouveau (#167).

Collie refuse d'ouvrir une fenêtre tmux (le nouvel onglet du téléphone revient avec un refus, indiquant window-size). Il ne s'agit pas d'une erreur dans la requête : sur les versions de tmux inférieures à 3.7, créer une fenêtre pendant que le window-size du serveur est manual fait planter tout le serveur (tmux #4849, corrigé dans la version 3.7), et un serveur planté emporte toutes les fenêtres avec lui. Collie refuse donc l'action et indique la version de tmux rencontrée. La solution est la ligne qu'il affiche (tmux set -g window-size latest sur ce serveur) ou tmux 3.7. Rien d'autre n'est affecté : toutes les autres actions sur ces panneaux continuent de fonctionner (Prérequis comporte la même réserve).

Collie consigne tmux list: output did not parse et le tableau de bord reste vide. Ce n'est pas un plantage : certaines versions de tmux (3.4, pas 3.6b) échappent le séparateur que cet adaptateur lit en sortie d'un listing -F. Collie gère désormais les deux formats ; un listing qui donne zéro ligne est donc signalé comme une erreur mux au lieu d'être enregistré comme un herd vide. La ligne d'erreur précise la version de tmux et le nombre de lignes observées. Si le problème persiste, notez la version de tmux -V et ouvrez un ticket ; la correction concerne l'adaptateur, pas votre .env.

herdr plugin list affiche l'ancienne version après un update. Comportement attendu : Herdr met en cache le manifeste lu au moment de l'installation ou du lien. La référence sur ce qui s'exécute est l'empreinte de build en bas de page, ou bin/collie version. Pour un clone lié, update recrée le lien et cela se corrige automatiquement (forcez-le avec herdr plugin link "$(pwd)") ; sur Herdr ≥0.8.0, le manifeste est de toute façon relu depuis le disque.

Le téléphone affiche une interface obsolète après une recompilation. Le cache du service worker d'une PWA dépend de l'origine. Accéder à Collie via deux origines différentes (un domaine personnalisé et le host:8787 brut) crée deux installations, chacune mettant en cache son propre bundle. Le tampon de build en bas de page (vX.Y.Z · sha · time) indique le bundle en cours d'exécution ; Collie signale ce qu'il sert via l'en-tête X-Collie-Build et /api/config. En cas de discordance, le bas de page propose « new build — tap to update. » Sinon, rouvrez la PWA à plusieurs reprises (le SW se met à jour automatiquement) ou effacez les données de site pour cette origine. Bonne pratique : choisissez une seule origine HTTPS et conservez-la. (En simple HTTP, le SW ne peut pas s'enregistrer : le contenu est toujours à jour, mais sans les fonctionnalités PWA.)

J'ai enregistré une machine dans Herdr et le téléphone ne l'affiche pas. Comportement attendu. Les machines enregistrées dans Herdr constituent la liste propre à son client, et un crew est propre à Collie ; aucune liste n'alimente l'autre. Pour joindre cette machine depuis le téléphone, enrôlez-la : collie crew add <ssh-host> sur le lead, puis collie restart sur le lead et collie crew status pour vérifier le lien. Ajouter ou supprimer une machine dans Herdr ne modifie rien dans le crew (Machines Herdr et le crew).

Une mise à jour lancée depuis le téléphone reste bloquée à l'étape de staging. Sur Collie jusqu'à la version 1.6.0, une mise à jour déclenchée sur le téléphone pouvait préparer la nouvelle version puis s'arrêter : le runner effectuant le basculement n'était jamais démarré, le service continuait de servir l'ancienne version, et l'enregistrement de l'exécution restait à l'état staging avec le verrou actif. Trois éléments réunis le confirment : collie update --status indique staging (ou, après dix minutes, interrupted — the updater is gone), le répertoire de version de la nouvelle release existe sous versions/, et le journal du runner à ~/.config/collie/collie.log fait 0 octet. Un collie update saisi dans un shell sur la même machine fonctionnait toujours, ce qui correspond au même défaut vu sous un autre angle. Il est corrigé à partir de la release suivante : le passage de relais attend désormais la confirmation du runner par le gestionnaire utilisateur, et un passage de relais refusé est signalé comme un échec avec la raison fournie par le gestionnaire.

Pour débloquer une machine déjà coincée, ne faites rien pendant dix minutes : une exécution dont l'updater a disparu cesse de bloquer une nouvelle tentative dix minutes après sa dernière transition, et l'appui suivant fonctionne. Pour la débloquer immédiatement, supprimez l'enregistrement, le verrou et le fichier de progression du staging, puis vérifiez ce qu'indique --status :

collie update --status            # note the pid it names
ps -p <pid> -o command=           # empty output: the updater really is gone
rm -f ~/.local/state/collie/update.json ~/.local/state/collie/update.lock
rm -f ~/.local/state/collie/update-staging-*.log
collie update --status            # "no update has run on this install yet"

Aucune commande ne nettoie une exécution obsolète, et ces trois fichiers constituent l'intégralité de l'état laissé par un staging bloqué. Une instance avec suffixe les conserve dans ~/.local/state/collie-<name>/ à la place. Ne jamais supprimez ces fichiers pendant qu'une mise à jour est en cours d'exécution, et vérifiez d'abord le pid : un updater actif dont vous avez retiré le verrou modifiera current sans aucune protection. Ne touchez pas à versions/. Le répertoire de version partiellement préparé est inoffensif, la nouvelle tentative réécrit dedans, et le nettoyage de rétention supprime ce dont il n'a plus besoin.