Aller au contenu principal

Problemes connus

Chatbotaurus, comme tout systeme complexe, peut rencontrer des problemes occasionnels. Ce guide fournit des solutions pour les cas les plus courants.

Besoin d'aide pour un probleme non liste ici ?

Ouvrez une issue sur notre depot Forgejo ou contactez-nous a contact@chatbotaurus.com.

Infrastructure Podman​

Conteneur qui ne demarre pas​

Si un conteneur refuse de demarrer apres podman run ou podman start :

  1. Verifiez les logs du conteneur : 
    sudo podman logs chatbotaurus-<service>
  2. Verifiez que le reseau existe : 
    sudo podman network ls | grep chatbotaurus-network
    sudo podman network ls | grep mgaas-network
  3. Si le reseau manque, recreez-le : 
    sudo podman network create chatbotaurus-network --subnet 172.28.0.0/16
    sudo podman network create mgaas-network --subnet 172.29.0.0/16

Conflit de port​

Si un port est deja utilise :

netstat -ano | grep PORT_NUMBER

Sur Windows, si wslrelay.exe occupe le port :

wsl --shutdown

Ports courants a verifier : 5432 (PostgreSQL), 6333 (Qdrant), 6379 (Valkey), 11434 (Ollama), 8180 (Keycloak), 8200 (Vault).

Resolution DNS entre conteneurs (aardvark-dns)​

Si les conteneurs ne se resolvent pas entre eux par nom :

  1. Verifiez que aardvark-dns est installe : 
    which aardvark-dns
  2. Redemarrez le reseau Podman : 
    sudo podman network reload --all
  3. En dernier recours, recreez les conteneurs (les volumes sont preserves).

Volumes et persistance des donnees​

Si des donnees sont perdues apres un redemarrage de conteneur :

  1. Verifiez que les volumes sont correctement montes : 
    sudo podman inspect chatbotaurus-<service> | grep -A5 "Mounts"
  2. Assurez-vous d'utiliser des volumes nommes plutot que des bind mounts temporaires.

Ollama et modeles IA​

Ollama Out of Memory (OOM)​

Le modele qwen3:8b necessite environ 8 Go de RAM. Si Ollama est tue par le kernel (OOM killer) :

  1. Verifiez la memoire disponible : 
    free -h
  2. Verifiez les limites du conteneur : 
    sudo podman inspect chatbotaurus-ollama | grep -i memory
  3. Solutions :
    • Augmentez la limite memoire du conteneur Ollama a 16 Gi minimum
    • Reduisez le nombre de modeles charges simultanement
    • Utilisez tomng/nanbeige4.1:3b pour les taches legeres au lieu de qwen3:8b

Modele non trouve​

Si Ollama retourne une erreur "model not found" :

# Listez les modeles disponibles
sudo podman exec chatbotaurus-ollama ollama list

# Telechargez le modele manquant
sudo podman exec chatbotaurus-ollama ollama pull qwen3:8b
sudo podman exec chatbotaurus-ollama ollama pull tomng/nanbeige4.1:3b
sudo podman exec chatbotaurus-ollama ollama pull qwen3-embedding:0.6b

Latence elevee des reponses​

Si les reponses du LLM sont lentes (> 8s pour une requete complexe) :

  1. Verifiez l'utilisation CPU
  2. Verifiez qu'un seul modele est charge en memoire (le swap entre modeles est couteux)
  3. Activez la degradation gracieuse si necessaire (voir architecture PODIUM, 5 niveaux)

Vault (Gestion des secrets)​

Vault re-sealed​

Vault peut se re-sceller automatiquement apres un redemarrage. Symptome : erreur 503 "Vault is sealed".

  1. Verifiez le statut : 
    sudo podman exec chatbotaurus-vault vault status
  2. Descellement (unseal) avec les cles : 
    sudo podman exec chatbotaurus-vault vault operator unseal <UNSEAL_KEY_1>
    sudo podman exec chatbotaurus-vault vault operator unseal <UNSEAL_KEY_2>
    sudo podman exec chatbotaurus-vault vault operator unseal <UNSEAL_KEY_3>
attention

Les cles de descellement doivent etre stockees de maniere securisee et separee. Ne les commitez jamais dans le depot.

Secrets non injectes dans les conteneurs​

Si un conteneur MCP deploye ne recoit pas ses secrets :

  1. Verifiez que le chemin Vault est correct : secret/data/mcp-servers/{serverId}
  2. Verifiez les permissions du token Vault utilise par le SecretsManager
  3. Consultez les logs du service de deploiement

MCP Gateway​

Erreur de session Streamable HTTP​

Si vous recevez une erreur 404 ou "session not found" :

  1. Verifiez que le header Mcp-Session-Id est present dans la requete
  2. Les sessions expirent apres 30 minutes d'inactivite (TTL configurable)
  3. Reinitialisez la session avec une requete initialize sur POST /api/v1/mcp

Erreur JSON-RPC batch​

Le batching est limite a 50 requetes par batch. Si vous depassez cette limite :

Erreur: "Batch size exceeds maximum of 50 requests"

Decoupez vos requetes en lots de 50 maximum.

Connecteur MCP qui echoue​

Si un connecteur (Odoo, n8n, etc.) ne repond pas :

  1. Verifiez la connectivite reseau vers le service cible : 
    curl -s http://<service-host>:<port>/health
  2. En mode demo (VPS2), la latence doit etre < 5ms
  3. En mode production (infra client), la latence peut atteindre 200ms - verifiez les timeouts
  4. Verifiez les credentials dans Vault

Base de donnees​

PostgreSQL connexion refusee​

Error: connect ECONNREFUSED 127.0.0.1:5432
  1. Verifiez que le conteneur tourne : 
    sudo podman ps | grep chatbotaurus-postgres
  2. Verifiez les logs : 
    sudo podman logs chatbotaurus-postgres
  3. Verifiez que le port 5432 n'est pas utilise par une autre instance PostgreSQL locale

Qdrant index corrompu​

Si Qdrant retourne des erreurs de lecture :

  1. Verifiez les logs : 
    sudo podman logs chatbotaurus-qdrant
  2. En dernier recours, recreez la collection (les embeddings devront etre regeneres) : 
    curl -X DELETE http://localhost:6333/collections/<collection_name>

Frontend (Next.js)​

Erreur de build Next.js​

cd packages/new-ui
pnpm build

Si le build echoue :

  1. Nettoyez le cache : rm -rf .next
  2. Reinstallez les dependances : pnpm install
  3. Verifiez les erreurs TypeScript : pnpm tsc --noEmit

Variables d'environnement manquantes​

Si le frontend ne se connecte pas au backend :

  1. Verifiez .env ou .env.local dans packages/new-ui/
  2. Les variables Next.js publiques doivent commencer par NEXT_PUBLIC_
  3. Redemarrez le serveur de dev apres modification des variables d'environnement

Keycloak (Authentification)​

Impossible de se connecter​

  1. Verifiez que Keycloak est accessible : http://localhost:8180
  2. Verifiez les logs : 
    sudo podman logs chatbotaurus-keycloak
  3. Verifiez la configuration du realm et du client dans la console d'administration

Performance et monitoring​

Metriques a surveiller​

MetriqueSeuil d'alerteAction
RAM totale VPS1> 24 GoReduire les limites conteneurs
CPU VPS1> 85%Activer degradation gracieuse
Latence tool calling> 8sVerifier cache, reseau
Cache hit rate< 80%Verifier configuration Valkey

Besoin d'aide supplementaire ?​

Si votre probleme n'est pas couvert ici :

  1. Ouvrez une issue sur Forgejo
  2. Contactez-nous : support@chatbotaurus.com
  3. Consultez les diagnostics integres pour generer un rapport technique