Dépannage

Diagnostiquez du serveur vers le client : processus et santé, authentification, chemin projet, identifiant, puis affichage client.

Serveur injoignable

1. Consultez la barre système, le gestionnaire de service ou docker compose ps.

2. Trouvez le port réel. Une version publiée peut passer de 50505 à 50506–50514, puis à un port attribué par le système ; le natif écrit port.txt dans le dossier applicatif.

3. Appelez le health check :

   curl --fail-with-body http://localhost:50505/api/health

4. Depuis une autre machine, testez l’origine publique et le pare-feu/proxy, pas localhost.

5. Dans l’application bureau, revenez à la connexion serveur et testez l’origine sans /api.

Si la santé fonctionne localement mais pas à distance, concentrez-vous sur pare-feu, proxy, DNS, TLS et WebSocket. Si elle échoue localement, inspectez logs et code de sortie du service/conteneur.

Mauvais serveur mémorisé par le bureau

L’application mémorise les origines récentes et découvre un serveur natif via port.txt. Utilisez l’écran de connexion/login pour changer de serveur. Ne supprimez pas des données serveur pour effacer une URL côté client.

Si les versions majeures client/serveur sont incompatibles, mettez à jour le composant le plus ancien. Leurs flux de mise à jour sont séparés.

Le serveur ne démarre pas

Conflit de port

Stib applique normalement le fallback. Si tout échoue, identifiez le processus qui réserve la plage et une éventuelle politique empêchant le port attribué. Ne lancez pas deux serveurs sur le même dossier de données.

Permissions de données

Le processus doit lire/écrire son dossier applicatif et chaque dépôt. Sous Docker, /data et les montages de dépôts doivent être accessibles à l’utilisateur non root de l’image. Corrigez propriété/montages plutôt que d’exécuter en root.

Migration ou base

Conservez le log original et la version exacte. Restaurez le paquet/image officiel si des migrations ont été modifiées. Ne changez jamais une migration appliquée pour faire disparaître une erreur de hash.

Utilisez la sauvegarde intégrée tant que le serveur est sain. Pour un diagnostic SQLite hors ligne, arrêtez tous les processus puis travaillez sur une copie ; ne lancez pas de réparation contre un fichier de production actif.

L’agent ne démarre pas

Vérifiez dans l’ordre :

1. carte dans une colonne active, non différée, verrouillée, archivée ou déjà en cours ;
2. dépôt accessible depuis le serveur ;
3. identifiant visible dans cette portée, valide, non verrouillé, avec quota et accès modèle ;
4. runtime/capacité fournisseur détecté ;
5. worktree créable et aucun blocage Git ;
6. sandbox disponible si le projet l’exige ;
7. erreur de lancement dans les logs serveur.

Ne relancez qu’après correction. Répéter des erreurs OAuth/quota peut verrouiller ou limiter un identifiant récupérable.

Agent en attente ou bloqué

Ouvrez Conversation et Historique. Il peut attendre question, validation de plan, message en file, réponse fournisseur, script, condition ou prochaine boucle. Le hub Agents affiche les attentes de tous les projets.

Après une annulation, inspectez Diff/Git. Un processus peut avoir écrit des fichiers avant de se bloquer.

Erreur Git ou worktree

• Confirmez le dépôt et que l’utilisateur serveur peut y exécuter Git.
• Rafraîchissez l’espace Git et inspectez changements non suivis/unstaged.
• Vérifiez collisions de branche/worktree et processus utilisant le dossier.
• Vérifiez clés SSH, known_hosts, remotes et authentification CLI fournisseur pour fetch/push/PR.
• Ne forcez pas le nettoyage d’un worktree dont le travail n’est pas préservé.

Authentification et OIDC

• 401 : session ou token absent/expiré ; reconnectez-vous.
• 403 : authentifié mais siège, rôle, portée projet, permission API ou fonction de licence manquant.
• Échec OIDC : vérifiez STIB_SERVER_ORIGIN, callback exact, HTTPS, découverte issuer, client ID/secret, scopes et heure serveur.
• Une clé API fonctionne seulement sur les routes projet autorisées par sa liste de permissions et les accès de son compte propriétaire. Utilisez un propriétaire dédié à faibles privilèges pour l’automatisation externe.

Conservez une voie super-admin testée avant de changer les méthodes de connexion.

Déconnexions WebSocket

Le board peut charger en HTTP alors que le direct échoue si le proxy ne transmet pas les upgrades ou coupe trop vite les connexions inactives. Vérifiez journal réseau, en-têtes, TLS et logs. La reconnexion récupère l’état serveur ; elle ne duplique pas le processus agent.

Intégration en erreur

Lancez le test de connexion, puis inspectez mapping et état de synchro. C’est le serveur/conteneur — pas le bureau — qui doit résoudre et joindre l’URL. Les cibles privées/loopback restent bloquées sauf activation volontaire de STIB_ALLOW_PRIVATE_URLS.

Vérifiez permissions fournisseur, quotas, pagination, webhooks et source faisant autorité pour chaque champ.

Logs et bundle de support

• Serveur natif : sous data/logs du dossier applicatif ou Voir/Exporter les logs serveur depuis la barre.
• Docker : docker compose logs stib et export configuré.
• Bureau : action native d’export/révélation des logs client.
• Activité produit : audit projet/organisation.

Notez versions client/serveur, type d’installation, origine/port réel, date/fuseau, IDs projet/carte et étapes. Retirez tokens, clés API, payloads d’identifiants, prompts privés et code source inutile.