Problèmes connus

Chatbotaurus, comme tout système complexe, peut rencontrer des problèmes occasionnels. Ce guide fournit des solutions pour les cas courants. Les noms de conteneurs sont ceux des fichiers podman-compose.yml (plan backend, services forge-*) et podman-compose.vps2.yml (plan client, services mcp-*).

Astuce : un problème qui n'est pas listé ici ?

Écrivez à support@chatbotaurus.com en suivant la marche décrite dans Diagnostics et signalement.

Par symptôme

Infrastructure Podman

Un conteneur ne démarre pas

1. Lisez les journaux du conteneur :

   podman logs forge-postgres
   

2. Vérifiez que les deux réseaux existent (les fichiers compose les déclarent externes et ne les créent pas) :

   podman network ls | grep -E "chatbotaurus-vps1|mgaas-vps2"
   

3. S'ils manquent, créez-les :

   podman network create chatbotaurus-vps1
   podman network create mgaas-vps2
   

4. Pour un service sous Quadlet, regardez l'unité systemd :

   systemctl --user status forge-api.service
   journalctl --user -u forge-api.service -n 100
   

Les services Quadlet ne redémarrent pas après un redémarrage de l'hôte

Les unités Quadlet tournent sous un compte de déploiement non privilégié (rootless). Sans le mode « linger » de systemd, elles s'arrêtent à la déconnexion et ne repartent pas au démarrage. Le script containers/scripts/enable-linger.sh l'active, une fois, par hôte. Il se lance en root, après la création du compte de déploiement, en lui passant le nom de ce compte : bash containers/scripts/enable-linger.sh <compte-deploiement> (le compte doit exister, sinon le script s'arrête et dit de le créer). Résultat attendu : des lignes [OK], dont lingering enabled, puis la vérification du répertoire d'exécution et du socket Podman de ce compte.

Conflit de port

Si un port est déjà utilisé :

ss -tlnp | grep <port>

Sous Windows (développement local) :

netstat -ano | Select-String "5432"

Ports publiés par défaut en développement : 5432 (PostgreSQL), 6380 (Valkey, pour ne pas entrer en collision avec un Redis local sur 6379), 6333 (Qdrant), 11434 (Ollama), 9000 (Authentik), 8200 (OpenBao).

Résolution DNS entre conteneurs

Si les conteneurs ne se résolvent pas entre eux par leur nom :

1. Vérifiez qu'ils sont sur le même réseau :

   podman inspect forge-api --format '{{json .NetworkSettings.Networks}}'
   

2. Vérifiez le moteur réseau de Podman (netavark attendu) :

   podman info | grep -i networkBackend
   

3. Rechargez les réseaux :

   podman network reload --all
   

4. En dernier recours, recréez les conteneurs (les volumes sont conservés).

Rappel : PostgreSQL et Valkey portent les alias postgres et valkey sur mgaas-vps2. Un service du plan client doit utiliser ces alias, pas forge-postgres.

Volumes et persistance des données

Si des données disparaissent après un redémarrage :

1. Vérifiez les volumes montés :

   podman inspect forge-postgres --format '{{json .Mounts}}'
   podman volume ls
   

2. Utilisez les volumes nommés des fichiers compose (noms logiques forge-pgdata, forge-valkey-data, forge-qdrant-data, entre autres) plutôt que des montages temporaires. Ces volumes sont external : leur nom réel est la clé name: du bloc volumes: (grep -n "name:" podman-compose.yml) et compose ne crée pas un volume externe absent. La création est décrite dans Déploiement avec Podman.

Déploiement

Ma modification n'apparaît pas en production

Le déploiement est tiré par l'hôte, toutes les 2 minutes, et seulement si la branche principale a avancé. Vérifiez dans l'ordre :

1. le champ sha de /api/v1/healthz correspond-il à votre commit ?

   curl -s https://app.<domaine>/api/v1/healthz | jq .
   

2. où en est le déploiement du front (ce script ne lit pas l'état du backend : l'étape 1 le prouve) ?

   bash scripts/deploy/suivre-autodeploy.sh
   

3. un commit qui ne touche que la documentation ne reconstruit pas l'image backend : c'est normal ;
4. si le service ne répond pas après un redémarrage, le script du backend revient à l'image précédente et l'indique dans son état.

Après un déploiement du front, rechargez la page en vidant le cache du navigateur : l'ancien wasm peut rester en cache.

Ollama et modèles IA

Ollama à court de mémoire (OOM)

Si Ollama est tué par le noyau :

1. Vérifiez la mémoire disponible :

   free -h
   

2. Vérifiez les limites du conteneur (fixées dans le plan compose) :

   podman inspect forge-ollama | grep -i memory
   

3. Solutions :
   • augmentez la limite mémoire si l'hôte le permet ;
   • réduisez le nombre de modèles chargés simultanément ;
   • choisissez un modèle plus petit (variable OLLAMA_MODEL).

Modèle introuvable

Si Ollama répond « model not found » :

# Modèles disponibles
podman exec forge-ollama ollama list

# Télécharger le modèle manquant
podman exec forge-ollama ollama pull <nom-du-modèle>

Le nom doit correspondre à celui que le backend demande (OLLAMA_MODEL).

Latence élevée des réponses

Si les réponses du LLM sont lentes :

1. Vérifiez l'utilisation CPU (podman stats --no-stream).
2. Vérifiez qu'un seul modèle est chargé : passer d'un modèle à l'autre est coûteux.
3. Le code prévoit une dégradation par paliers au-delà de 10 s de latence moyenne (voir Gestion des erreurs), mais les moteurs qu'elle coupe n'ont pas d'appelant de production : ne comptez pas dessus pour réduire la latence (voir Supervision).

OpenBao (gestion des secrets)

OpenBao scellé

OpenBao se scelle au redémarrage. Symptôme : erreur 503 sur les appels qui lisent un secret.

1. Vérifiez l'état (code de sortie 2 = scellé) :

   podman exec forge-openbao bao status
   

2. Descellez avec le seuil de clés défini à l'initialisation. La commande demande la clé à la saisie :

   podman exec -it forge-openbao bao operator unseal
   

   Répétez avec des clés distinctes jusqu'à Sealed: false.

Attention

Les clés de descellement se conservent séparément et en lieu sûr. Ne les commitez jamais dans le dépôt. La topologie de descellement est décrite dans le guide d'exploitation du coffre, hors de ce livre.

Un service ne reçoit pas ses secrets

1. Vérifiez qu'OpenBao est descellé (voir la section « OpenBao scellé » ci-dessus).
2. Vérifiez les permissions du jeton utilisé par le backend.
3. Consultez les journaux du backend :

   podman logs --tail 100 forge-api
   

Passerelle MCP

Erreur de session Streamable HTTP

Si vous recevez une erreur « session expired or unknown » (code JSON-RPC -32600) ou « missing Mcp-Session-Id » :

1. Vérifiez que l'en-tête Mcp-Session-Id est présent dans la requête ;
2. les sessions expirent après 30 minutes d'inactivité ;
3. ouvrez une nouvelle session par une requête initialize sur POST /api/v1/mcp.

Un connecteur échoue

Si un connecteur (Odoo, n8n, Matomo, entre autres) ne répond pas :

1. Identifiez le code d'erreur renvoyé :
   • TIMEOUT (504) : le service tiers est trop lent (voir timeout_ms du connecteur) ;
   • SERVICE_UNAVAILABLE (503) : connexion impossible ;
   • RATE_LIMITED (429) : limite de l'amont atteinte, respectez Retry-After ;
   • Forbidden avec SSRF_BLOCKED : l'URL de base fournie par le locataire vise le réseau interne, elle est refusée.
2. Vérifiez que le conteneur du service tourne :

   podman ps --filter name=mcp-
   

3. Vérifiez les identifiants du connecteur (variable token_env ou key_env du YAML, ou identifiants du locataire).
4. Lisez les logs du service concerné (podman logs mcp-n8n, par exemple).

Un connecteur est rejeté au démarrage

Au démarrage, forge-api journalise connector rejected by registry (EU compliance?) pour un connecteur dont gdpr_compliant vaut false ou dont la résidence des données n'est pas européenne. Corrigez le bloc compliance du YAML : voir Conception des connecteurs MCP.

Erreur CIRCUIT_OPEN (503)

Le disjoncteur d'un agent s'est ouvert après plusieurs échecs consécutifs. Il laisse repasser un essai après un court délai. Cherchez la cause des échecs dans les journaux de forge-api (modèle indisponible, connecteur en erreur), puis attendez le délai ou corrigez la cause.

Base de données et stockage

PostgreSQL : connexion refusée

1. Vérifiez que le conteneur tourne :

   podman ps | grep forge-postgres
   

2. Vérifiez les journaux :

   podman logs forge-postgres
   

3. Vérifiez que le port 5432 n'est pas pris par une autre instance PostgreSQL locale.

Qdrant : index corrompu

Si Qdrant renvoie des erreurs de lecture :

1. Lisez les journaux :

   podman logs forge-qdrant
   

2. Restaurez d'abord l'instantané de la collection (voir Sauvegarde et restauration).
3. En dernier recours, supprimez la collection (les embeddings devront être régénérés) :

   curl -X DELETE http://localhost:6333/collections/<collection>
   

Le stockage objet S3 refuse toutes les requêtes

Le service forge-seaweedfs est fermé par défaut : si les variables SEAWEEDFS_S3_* référencées par son fichier d'identités sont absentes ou vides, toute requête est refusée (403). Renseignez ces variables dans l'environnement du compose puis recréez le service : podman-compose -p chatbotaurus-vps1 up -d --force-recreate seaweedfs. Résultat attendu : une requête signée avec ces clés aboutit, une requête anonyme reçoit toujours 403.

Interface (Dioxus wasm)

Erreur de compilation du wasm

La commande de référence est :

cargo build -p forge-ui --target wasm32-unknown-unknown --bin chatbotaurus

Quatre causes reviennent souvent :

La cible wasm peut ne pas être installée. Installez-la :

rustup target add wasm32-unknown-unknown

Un cache cargo corrompu après une interruption brutale peut laisser des artefacts incohérents :

cargo clean -p forge-ui
cargo build -p forge-ui --target wasm32-unknown-unknown --bin chatbotaurus

Les erreurs de compilation Rust se diagnostiquent plus vite avec cargo check, qui s'arrête avant l'édition de liens :

cargo check -p forge-ui --target wasm32-unknown-unknown

Enfin, une Dioxus CLI obsolète se manifeste par des erreurs opaques à l'édition de liens ou à l'empaquetage. Réinstallez la dernière version 0.7 :

cargo install dioxus-cli --force

Le paquet de production se construit avec :

dx build --release --platform web --package forge-ui

Sous Windows, l'optimiseur wasm-opt peut planter et dx rend pourtant un code de sortie 0 : une ligne ERROR dans sa sortie suffit à refuser le paquet. La construction de production se fait sous Linux.

dx serve ne recharge plus

Il arrive que l'observateur de fichiers se désynchronise (montage croisé Windows/WSL). Arrêtez dx serve, puis relancez-le :

dx serve --package forge-ui --bin chatbotaurus --port 8080

La configuration du frontend est ignorée

Le frontend wasm ne lit pas les variables d'environnement système à l'exécution (il s'exécute dans le navigateur). Sa configuration est compilée :

• la marque, les liens et les offres affichés viennent de crates/forge-ui/src/config/site.rs ;
• l'adresse de l'API vient de crates/forge-ui/src/config/api.rs : en web, le chemin relatif /api/v1 du même domaine ; sur les cibles natives, la valeur de API_URL fixée à la compilation (défaut http://localhost:3000/api/v1).

Pour appliquer un changement : éditez le fichier, reconstruisez le wasm ; dx serve recharge automatiquement.

Le CSRF rejette les requêtes

Symptôme : 403 sur les POST, PUT ou DELETE.

Vérifiez :

1. que le cookie csrf-token est présent (outils du navigateur, onglet Application, Cookies) ;
2. que l'en-tête x-csrf-token est envoyé avec la même valeur que le cookie ;
3. que l'origine du frontend figure dans CORS_ORIGINS côté backend.

Le JWT est invalide après un redémarrage du backend

La valeur de JWT_SECRET doit rester stable d'un démarrage à l'autre. Si elle change (par exemple générée au hasard à chaque lancement), tous les jetons émis avant deviennent invalides. Fixez JWT_SECRET dans votre fichier d'environnement et chargez-le à chaque démarrage.

Authentik (authentification)

Connexion impossible

1. Vérifiez qu'Authentik répond (port 9000 en développement) :

   podman ps --filter name=authentik
   

2. Lisez les journaux (en développement forge-authentik, en production forge-authentik-server et forge-authentik-worker) :

   podman logs forge-authentik
   

3. Vérifiez l'application et le fournisseur OIDC dans la console d'administration.

Performance et surveillance

Seuils de dégradation

Le code prévoit de réduire les techniques d'IA quand l'un de ces seuils est franchi (crates/forge-core/src/mgaas/types.rs). Cette cascade est livrée mais non branchée (voir Supervision).

Les seuils (mémoire, processeur, latence) sont fixés dans le code et ne sont pas publiés ici.

VictoriaMetrics (forge-victoriametrics, port 8428) et VictoriaLogs (forge-victorialogs, port 9428) existent dans le compose de développement. Rien ne les alimente par défaut et aucune unité Quadlet ne les déploie : voir Supervision.

Besoin d'aide supplémentaire ?

1. Consultez les diagnostics intégrés pour rassembler les informations utiles.
2. Écrivez à support@chatbotaurus.com.

Voir aussi

• Diagnostics et signalement — rassembler santé, journaux et identifiant de requête avant d'écrire au support
• Gestion des conteneurs — commandes du quotidien : journaux, redémarrage, inspection, ressources
• Déploiement avec Podman — créer réseaux et volumes, suivre le déploiement tiré par l'hôte
• Variables d'environnement — chaque variable citée dans ces solutions, avec son défaut
• Gestion des erreurs — signification de chaque code d'erreur renvoyé par l'API