Dépannage

Ce guide vous aide à diagnostiquer et résoudre les problèmes courants avec Stib. Chaque section couvre les symptômes, les causes probables et les solutions étape par étape. Consultez aussi Configuration pour les options de paramétrage, Authentification pour les détails SSO/OIDC, System Tray pour l'intégration bureau, et Identifiants & Scripts pour la gestion des identifiants.

Bases du diagnostic

Avant d'examiner des problèmes spécifiques, utilisez ces vérifications rapides pour évaluer l'état de votre instance Stib.

Vérifier si le serveur fonctionne

Envoyez une requête au endpoint de vérification de santé :

curl http://localhost:50505/api/health

Un serveur en bonne santé répond :

{ "data": { "status": "ok" } }

Si vous n'obtenez aucune réponse, le serveur ne fonctionne pas ou n'est pas accessible à cette adresse.

Vérifier le port

Confirmez que Stib écoute sur le port attendu :

# macOS / Linux
lsof -i :50505

# Windows
netstat -ano | findstr :50505

Vérifier le processus serveur

# macOS / Linux
ps aux | grep stib

# Windows
tasklist | findstr stib

Vérification rapide de la base de données

Vérifiez que la base de données est accessible et non corrompue :

sqlite3 data/stib.db "PRAGMA integrity_check;"

Une base de données saine répond ok.

Accéder aux logs

Emplacement des fichiers de log

Stib écrit les fichiers de log dans le répertoire data/logs/ relatif au répertoire de travail du serveur. Les fichiers suivent un schéma de rotation journalière :

data/logs/stib.YYYY-MM-DD.log

Jusqu'à 7 fichiers de log sont conservés. Les fichiers plus anciens sont automatiquement supprimés.

Page de logs en temps réel

L'interface web inclut une page de logs en temps réel accessible à /logs. Elle fournit :

• Jusqu'à 500 entrées de log récentes
• Filtre par niveau (DEBUG, INFO, WARN, ERROR)
• Recherche textuelle avec debounce
• Streaming en direct via WebSocket
• Entrées extensibles avec champs et contexte de span
• Indicateur d'état de connexion (vert = connecté, rouge = déconnecté)

Contrôler le niveau de log

Le filtre de log par défaut est stib_server=info,tower_http=info. Pour augmenter la verbosité, définissez la variable d'environnement RUST_LOG :

RUST_LOG=stib_server=debug ./stib-server

Valeurs courantes de niveau de log :

Valeur	Description
error	Erreurs uniquement
warn	Erreurs et avertissements
info	Fonctionnement normal (par défaut)
debug	Informations de diagnostic détaillées
trace	Très verbeux, inclut tous les détails internes

Export et agrégation de logs

Stib supporte l'export de logs vers des systèmes d'agrégation externes :

Format	Système cible	Description
CLEF	Seq	Compact Log Event Format
GELF	Graylog	Graylog Extended Log Format
JSONL	N'importe quel endpoint	JSON Lines, un événement par ligne

Paramètres d'export :

Paramètre	Plage	Défaut	Description
batch_size	1–10 000	100	Événements par lot
flush_interval_secs	1–300	5	Secondes entre les envois

Les exports échoués sont réessayés jusqu'à 3 fois avec un backoff exponentiel (1s, 2s, 4s).

Problèmes courants — Serveur

Le serveur ne démarre pas : Permission refusée

Symptômes : Le serveur se ferme immédiatement avec une erreur de permission.

Cause : Le serveur ne peut pas créer ou écrire dans le répertoire data/logs/.

Solution :

1. Vérifiez que le répertoire data/ existe et est accessible en écriture :

   ls -la data/

2. Corrigez les permissions :

   chmod -R 755 data/

3. Si vous utilisez Docker, assurez-vous que le montage de volume a les bonnes permissions

Le serveur ne démarre pas : Port déjà utilisé

Symptômes : Le serveur se ferme avec une erreur Address already in use.

Cause : Un autre processus utilise déjà le port 50505.

Solution :

1. Trouvez ce qui utilise le port :

   lsof -i :50505

2. Arrêtez le processus en conflit, ou changez le port de Stib :

   SERVER_PORT=30002 ./stib-server

Le serveur ne démarre pas : Échec de migration de base de données

Symptômes : Le serveur se ferme avec une erreur de migration au démarrage.

Cause : Le schéma de la base de données est corrompu ou il y a un décalage de version après un downgrade.

Solution :

1. Consultez le fichier de log pour l'erreur de migration exacte
2. Si vous avez rétrogradé Stib, la base de données peut contenir des changements de schéma plus récents. Restaurez à partir d'une sauvegarde effectuée avant la mise à jour
3. En dernier recours, supprimez data/stib.db et redémarrez (cela supprime toutes les données)

DANGER

Supprimer le fichier de base de données efface tous les projets, cartes, historiques d'agents et paramètres. Essayez toujours de restaurer depuis une sauvegarde d'abord.

Le serveur ne démarre pas : Blocage au démarrage

Symptômes : Le serveur semble démarrer mais ne devient jamais accessible.

Cause : Le fichier de base de données peut être verrouillé par un autre processus.

Solution :

1. Assurez-vous qu'aucune autre instance de Stib ne fonctionne
2. Vérifiez les fichiers de verrouillage restants :

   ls data/stib.db-*

3. Si stib.db-wal et stib.db-shm existent mais qu'aucun processus Stib ne tourne, vous pouvez les supprimer en toute sécurité et redémarrer

Consommation mémoire élevée

Symptômes : Le processus serveur Stib consomme une quantité de mémoire anormalement élevée au fil du temps.

Cause : Le buffer de logs en mémoire, les connexions WebSocket actives ou de nombreuses sessions d'agents simultanées peuvent augmenter la consommation mémoire.

Solution :

1. Vérifiez le nombre d'agents en cours d'exécution et annulez ceux qui ne sont plus nécessaires
2. Réduisez le niveau de log à info ou warn s'il est défini sur debug ou trace
3. Redémarrez le serveur pour vider le buffer de logs en mémoire (2000 entrées)
4. Si le problème persiste, vérifiez les processus d'agents qui ne se sont pas terminés proprement :

   ps aux | grep claude

Problèmes courants — Agents

L'agent ne se lance pas

Symptômes : La carte affiche une erreur lors du lancement d'un agent. Le message d'erreur mentionne que Claude CLI est introuvable.

Cause : Le binaire claude n'est pas dans le PATH du serveur.

Solution :

1. Vérifiez que Claude Code est installé :

   claude --version

2. S'il est installé mais introuvable, ajoutez son emplacement au PATH avant de démarrer Stib :

   export PATH="$PATH:/chemin/vers/claude"

3. Avec Docker, assurez-vous que le CLI Claude est disponible à l'intérieur du conteneur

Agent bloqué ou non réactif

Symptômes : L'agent semble fonctionner mais ne produit aucune sortie. La carte affiche un indicateur de chargement indéfiniment.

Cause : Le processus de l'agent peut attendre une entrée ou a rencontré un état irrécupérable.

Solution :

1. Annulez l'agent depuis le panneau overlay de la carte ou le menu d'actions
2. Vérifiez la conversation de l'agent pour des messages d'erreur
3. Relancez l'agent — l'historique de session est préservé pour le contexte

Relais de saturation de contexte

Symptômes : La sortie de l'agent mentionne des limites de contexte. Une nouvelle session d'agent démarre automatiquement.

Cause : La fenêtre de contexte de l'agent Claude Code est pleine. C'est un comportement normal — Stib le gère automatiquement.

Solution :

Aucune action nécessaire. Stib effectue un relais de contexte automatique : il lance un nouvel agent et transfère le contexte de conversation. Le travail continue sans interruption.

INFO

Le relais de contexte est une fonctionnalité intégrée. Le nouvel agent reçoit un résumé de la conversation précédente et continue là où l'agent précédent s'est arrêté.

Message d'erreur de l'agent sur la carte

Symptômes : La carte affiche un badge d'erreur rouge avec un message d'erreur.

Cause : Le processus de l'agent s'est terminé avec une erreur. L'erreur est capturée et stockée sur la carte.

Solution :

1. Cliquez sur la carte pour ouvrir l'overlay et lire le message d'erreur complet
2. Les causes courantes incluent :
   • Identifiants Claude invalides ou expirés
   • Problèmes de connectivité réseau vers l'API d'Anthropic
   • Problèmes de permissions de fichiers dans le worktree
3. Corrigez la cause sous-jacente, puis relancez l'agent depuis le menu d'actions de la carte

Problèmes courants — Connexion

Déconnexions WebSocket

Symptômes : Les mises à jour en temps réel s'arrêtent. L'interface affiche un statut déconnecté. Les modifications des autres clients ne sont pas reflétées.

Cause : La connexion WebSocket a été interrompue à cause de problèmes réseau, de timeouts du proxy ou d'un redémarrage du serveur.

Solution :

1. Vérifiez votre connexion réseau
2. Si vous êtes derrière un reverse proxy, assurez-vous que le transfert WebSocket est configuré :

   # Exemple Nginx
   location / {
       proxy_pass http://localhost:50505;
       proxy_http_version 1.1;
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection "upgrade";
   }

3. Augmentez les valeurs de timeout du proxy si les déconnexions surviennent après une période d'inactivité
4. Le client se reconnecte automatiquement — attendez quelques secondes

Erreurs d'authentification (401 / 403)

Symptômes : Les requêtes API échouent avec 401 Unauthorized ou 403 Forbidden.

Cause : Token d'authentification manquant, invalide ou expiré.

Solution :

1. Déconnectez-vous et reconnectez-vous pour rafraîchir votre token
2. Vérifiez que l'authentification est correctement configurée dans les paramètres
3. Si vous utilisez OIDC, vérifiez que votre session auprès du fournisseur d'identité n'a pas expiré
4. Effacez les cookies et le stockage local du navigateur si le problème persiste

Échecs de callback OIDC

Symptômes : Après l'authentification auprès de votre fournisseur d'identité, vous êtes redirigé vers Stib avec une erreur.

Cause : Décalage de configuration OIDC entre Stib et le fournisseur d'identité.

Solution :

1. Vérifiez que l'URI de redirection dans votre fournisseur d'identité correspond exactement à l'URL de callback de Stib
2. Vérifiez que STIB_SERVER_ORIGIN est défini sur votre URL publique
3. Assurez-vous que le client ID et le client secret sont corrects dans les paramètres de Stib
4. Consultez les logs du serveur pour les messages d'erreur OIDC détaillés

Problèmes CORS avec reverse proxy

Symptômes : La console du navigateur affiche des erreurs CORS. Les requêtes API échouent depuis le frontend.

Cause : Le reverse proxy ne transfère pas correctement les en-têtes, ou STIB_SERVER_ORIGIN est mal configuré.

Solution :

1. Définissez STIB_SERVER_ORIGIN sur votre URL publique (ex. https://stib.example.com)
2. Assurez-vous que votre reverse proxy transmet les en-têtes d'origine
3. N'ajoutez pas d'en-têtes CORS supplémentaires dans le proxy — Stib gère le CORS en interne

Problèmes courants — Mobile

L'application mobile ne se connecte pas

Symptômes : L'application mobile affiche une erreur de connexion en essayant d'atteindre le serveur.

Cause : Le serveur n'est pas accessible depuis le réseau de l'appareil mobile.

Solution :

1. Assurez-vous que l'appareil mobile et le serveur Stib sont sur le même réseau (ou que le serveur est accessible publiquement)
2. Utilisez l'adresse IP ou le nom d'hôte du serveur, pas localhost ou 127.0.0.1
3. Vérifiez le format de l'URL : http://<ip-serveur>:50505 (incluez le port)
4. Vérifiez les règles du pare-feu — le port 50505 doit être ouvert pour les connexions entrantes
5. Testez la connectivité depuis l'appareil mobile :

   http://<ip-serveur>:50505/api/health

Échecs de scan du QR code

Symptômes : L'application mobile ne peut pas scanner ou traiter le QR code depuis les paramètres.

Cause : Le QR code encode l'URL du serveur, qui peut ne pas être accessible depuis l'appareil mobile.

Solution :

1. Assurez-vous que l'URL du QR code utilise une adresse accessible depuis l'appareil mobile (pas localhost)
2. Si vous utilisez un reverse proxy, vérifiez que STIB_SERVER_ORIGIN est correctement défini
3. Essayez la saisie manuelle de connexion comme alternative

Authentification sur mobile

Symptômes : La connexion échoue sur l'application mobile alors qu'elle fonctionne dans l'interface web.

Cause : Problèmes de token d'authentification ou de flux OIDC spécifiques à l'application mobile.

Solution :

1. Pour l'authentification par mot de passe : vérifiez que les identifiants sont corrects
2. Pour OIDC/SSO : assurez-vous que le fournisseur d'identité autorise les redirections de l'application mobile
3. Vérifiez que l'URL du serveur est correcte et accessible
4. Essayez de vous déconnecter et de vous reconnecter

Problèmes courants — Base de données

Base de données verrouillée

Symptômes : Les logs du serveur affichent des erreurs « database is locked ». Les opérations échouent par intermittence.

Cause : Plusieurs processus tentent d'accéder simultanément à la base de données SQLite, ou un processus précédent ne s'est pas arrêté proprement.

Solution :

1. Assurez-vous qu'une seule instance du serveur Stib fonctionne
2. Arrêtez le serveur, supprimez les fichiers WAL restants si aucun processus n'est actif :

   rm data/stib.db-shm data/stib.db-wal

3. Redémarrez le serveur

WARNING

Ne supprimez les fichiers WAL (stib.db-shm, stib.db-wal) que lorsque le serveur est complètement arrêté. Les supprimer pendant que le serveur fonctionne peut causer une perte de données.

Erreurs de migration

Symptômes : Le serveur ne démarre pas avec un message d'erreur lié aux migrations.

Cause : La version du schéma de la base de données ne correspond pas à la version attendue par le binaire Stib en cours d'exécution.

Solution :

1. Consultez le log pour identifier la migration spécifique qui a échoué
2. Si vous avez mis à jour Stib, la migration devrait s'exécuter automatiquement — vérifiez les permissions de fichiers sur la base de données
3. Si vous avez rétrogradé Stib, restaurez à partir d'une sauvegarde effectuée avant la mise à jour
4. En dernier recours, recommencez à zéro en supprimant le fichier de base de données (perte de données)

Problèmes de mode WAL

Symptômes : Avertissements de corruption de base de données, comportement inattendu après un crash ou une coupure de courant.

Cause : Les fichiers WAL (Write-Ahead Logging) de SQLite peuvent être incomplets après un arrêt non propre.

Solution :

1. Arrêtez le serveur
2. Exécutez une vérification d'intégrité :

   sqlite3 data/stib.db "PRAGMA integrity_check;"

3. Si la vérification signale des problèmes, restaurez depuis la sauvegarde la plus récente
4. Redémarrez le serveur

Référence des variables d'environnement

Variable	Défaut	Description
RUST_LOG	stib_server=info,tower_http=info	Filtre de niveau de log
DATABASE_URL	sqlite://data/stib.db?mode=rwc	Chaîne de connexion à la base de données SQLite
SERVER_HOST	0.0.0.0	Adresse sur laquelle le serveur écoute
SERVER_PORT	50505	Port sur lequel le serveur écoute
CLAUDE_CONFIG_DIR	(défaut Claude CLI)	Répertoire personnalisé pour les profils OAuth Claude
ANTHROPIC_API_KEY	(aucun)	Clé API pour Claude (alternative aux identifiants OAuth)
STIB_SERVER_ORIGIN	(aucun)	URL publique pour CORS et redirections OIDC

Obtenir de l'aide

Vous ne parvenez pas à résoudre votre problème ? Consultez la FAQ pour des réponses aux questions fréquentes, ou contactez-nous avec votre sortie de log et une description du problème.