dictia-public/deployment/docs/TROUBLESHOOTING.md

Troubleshooting — DictIA

WhisperX OOM (Out of Memory)

Symptome: Container whisperx-asr crash ou restart en boucle.

Cause: Modele trop gros pour la RAM/VRAM disponible.

Solutions:

# Utiliser un modele plus petit dans .env
ASR_MODEL=medium   # au lieu de large-v3

# Augmenter la limite memoire (local-cpu)
# Editer docker-compose.local-cpu.yml
deploy:
  resources:
    limits:
      memory: 24G   # au lieu de 18G

Diarisation 403 Forbidden

Symptome: Erreur 403 lors de la transcription avec diarisation.

Cause: Token HuggingFace manquant ou conditions non acceptees.

Solution:

1. Creer un token: https://huggingface.co/settings/tokens
2. Accepter les conditions: https://huggingface.co/pyannote/speaker-diarization-3.1
3. Ajouter dans .env:

HF_TOKEN=hf_votre_token

4. Redemarrer: docker compose -f deployment/docker/docker-compose.<profil>.yml restart

GPU non detecte (local-gpu)

Symptome: nvidia-smi fonctionne mais Docker ne voit pas le GPU.

Solution:

# Installer nvidia-container-toolkit
sudo apt install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

# Verifier
docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi

Upload echoue (fichiers volumineux)

Symptome: Upload de gros fichiers (>100MB) echoue.

Causes possibles:

• Timeout Nginx/reverse proxy
• Limite upload trop basse

Solutions:

# Si Nginx: verifier client_max_body_size dans dictia.conf
client_max_body_size 500M;

# Si Tailscale Serve: pas de limite cote Tailscale

# Timeout gunicorn (dans le Dockerfile, deja a 600s)
# Pour des fichiers tres longs, augmenter dans docker-compose:
environment:
  - GUNICORN_TIMEOUT=1200

Container dictia "unhealthy"

Symptome: docker ps montre "unhealthy" pour le container dictia.

Diagnostic:

# Voir les logs
docker logs dictia --tail 50

# Tester manuellement
docker exec dictia python3 -c "import urllib.request; urllib.request.urlopen('http://localhost:8899/health')"

Causes courantes:

• .env mal configure (SECRET_KEY manquant)
• Base de donnees corrompue (restaurer backup)
• Port 8899 deja utilise

ASR Proxy: "No GPU available"

Symptome: Transcription echoue avec "No GPU available in any Canadian zone".

Causes:

• GCP n'a pas de GPU disponible (capacite epuisee)
• Credentials GCP expirees
• Budget mensuel atteint

Diagnostic:

# Verifier le statut du proxy
curl -s http://localhost:9090/health | python3 -m json.tool

# Verifier les stats (budget)
curl -s http://localhost:9090/stats | python3 -m json.tool

# Voir les logs
journalctl -u asr-proxy --since "1 hour ago"

Solutions:

• Attendre (GCP libere des GPUs regulierement)
• Le proxy reessaie automatiquement apres un cooldown de 3 minutes
• Verifier le dashboard: http://localhost:9090

Build Docker lent/echoue

Symptome: docker build prend trop de temps ou echoue.

Solutions:

# Limiter les ressources si le VPS est petit
docker build --memory=2g --cpus=2 -t innova-ai/dictia:latest .

# Nettoyer le cache Docker si le disque est plein
docker builder prune -f
docker image prune -f

Base de donnees corrompue

Symptome: Erreur SQLite au demarrage.

Solution:

# Restaurer le dernier backup
bash deployment/tools/restore.sh backups/dictia-LATEST.tar.gz

# Ou recreer la base (perd les donnees)
rm data/instance/transcriptions.db
docker compose -f deployment/docker/docker-compose.<profil>.yml restart

Port 8899 deja utilise

# Trouver qui utilise le port
sudo lsof -i :8899
# ou
sudo ss -tlnp | grep 8899

# Arreter le processus ou changer le port dans docker-compose
ports:
  - "8900:8899"   # utiliser 8900 a la place

Mise a jour qui casse tout

# Rollback: revenir au commit precedent
cd dictia
git log --oneline -5  # trouver le bon commit
git checkout <commit-hash>

# Rebuild et redemarrer
docker build -t innova-ai/dictia:latest .
docker compose -f deployment/docker/docker-compose.<profil>.yml down
docker compose -f deployment/docker/docker-compose.<profil>.yml up -d

Commande de diagnostic rapide

# Tout verifier d'un coup
bash deployment/tools/health-check.sh --json | python3 -m json.tool