# Dépannage — Immbot AI

| Symptôme | Cause probable | Solution |
|---|---|---|
| « Impossible de charger les modèles » dans le chat | `OPENROUTER_API_KEY` absente/invalide | Renseigner la clé dans `.env`, redémarrer ; tester : `curl -H "Authorization: Bearer $KEY" https://openrouter.ai/api/v1/models` |
| Le chat répond toujours « Je ne trouve pas une réponse… » | Ingestion non faite ou vide | `pnpm ingest` ; vérifier Admin → Cours & contenu (≈ 2 000 fragments) |
| Première ingestion très lente | Téléchargement du modèle d'embeddings (~120 Mo) | Normal une seule fois (cache `data/models/`) |
| `mutex lock failed` en fin de script | Nettoyage onnxruntime à la sortie du processus | Bénin — n'affecte ni le serveur ni les données |
| Erreur 429 « budget atteint » | Plafonds d'usage | Admin → Paramètres (budgets) ou attendre le lendemain |
| « Le modèle X n'accepte pas les images » | Modèle sans vision | Choisir le préréglage « Meilleur pour les images » |
| Connexion refusée après plusieurs essais | Rate-limit 8 échecs/15 min | Attendre le délai indiqué |
| Bannière ambre persistante en haut | Compte admin d'amorçage encore actif | Créer un compte personnel puis désactiver `admin` (et `DISABLE_INITIAL_ADMIN=true`) |
| Réponses sans citations en mode Cours | Le modèle ignore la consigne (rare) ou balises invalides neutralisées | Vérifier Admin → Vue générale (citations invalides) ; changer de modèle ; les balises inventées sont supprimées par conception |
| Port 3070 occupé | Autre instance | `lsof -i :3070` puis arrêter, ou changer le port dans package.json |
| Base corrompue / à repartir | — | Arrêter, restaurer `backups/…` (ou supprimer `data/immbot.db` puis `pnpm seed && pnpm ingest` — les données étudiantes sont alors perdues) |
| Type d'erreur `SyntaxError … .ts` dans les scripts | Node < 24 | Utiliser Node ≥ 24 (type stripping natif) |

## Journaux utiles

- Serveur : sortie standard (PM2 : `pm2 logs immbot-ai`).
- Sécurité : Admin → Sécurité (journal des connexions).
- Ingestion : Admin → Cours & contenu (rapport par exécution) et `docs/ingestion-report.md`.
- Coûts/erreurs API : Admin → Vue générale.