Troubleshooting — Aurora Nexus (MVP)

Ce document sert de guide de dépannage rapide pour l’interface Admin (backoffice) et la stack Docker (API / Ingestion / Gateway / Postgres / Qdrant / MinIO).

1) Sources de vérité (important)

Aurora Nexus utilise deux niveaux de configuration :

A) Configuration “Infra” (dans `.env` à la racine)

À conserver côté serveur, stable, et à versionner uniquement via .env.example (jamais de secrets en Git).

Exemples (non exhaustif) :

Accès services : DATABASE_URL, QDRANT_URL, S3_ENDPOINT, REDIS_URL, ports HOST_*
Secrets techniques obligatoires :
- LLM_CREDENTIALS_ENC_KEY : clé Fernet pour chiffrer/déchiffrer les credentials BYOK en base (ne pas changer sans plan de migration)
- GATEWAY_INTERNAL_SECRET : secret pour les appels internes API → Gateway
MinIO root : MINIO_ROOT_USER, MINIO_ROOT_PASSWORD (contraintes MinIO : user ≥ 3 chars, password ≥ 8 chars)

B) Configuration “Métier” (en base Postgres via l’UI Admin / API)

Modifiable sans redéployer.

Exemples :

BYOK / Providers : providers activés, modèles, credentials par tenant (llm_providers, llm_models, llm_credentials…)
Paramètres fonctionnels : RAG (MMR, RETRIEVE_K), cache, prompts, etc.

Règle de priorité runtime (MVP) :

Pour exécuter des requêtes LLM : les credentials en base (UI Admin → Providers → Credentials) priment.
Les variables .env type OPENROUTER_API_KEY servent au bootstrap/ops (catalogue modèles, scripts), pas à piloter le runtime tenant quand BYOK est en place.

2) Checklist “stack OK”

Sur le serveur :

docker compose ps : tous les services attendus sont Up (et healthy quand applicable)
API : curl http://127.0.0.1:${HOST_API_PORT:-18500}/api/health
Gateway : curl http://127.0.0.1:${HOST_GATEWAY_PORT:-17500}/health
UI : vérifier que NEXT_PUBLIC_API_URL pointe vers le bon domaine (ex. https://nexus.votredomaine.tld)

2.1 Checklist MinIO “OK”

Objectif : la console MinIO est accessible via son domaine public (ex. https://console-minio.votredomaine.tld/login) et l’API S3 fonctionne pour l’upload/téléchargement.

Variables .env à vérifier

Credentials :
- MINIO_ROOT_USER (≥ 3 caractères)
- MINIO_ROOT_PASSWORD (≥ 8 caractères)
URLs (si vous exposez MinIO via reverse-proxy) :
- MINIO_BROWSER_REDIRECT_URL=https://console-minio.votredomaine.tld (sans /login)
- MINIO_SERVER_URL=<URL publique de l’API S3 si existante> (optionnel selon votre proxy)
Backend :
- S3_ENDPOINT=http://minio:9000 (accès interne Docker)
- S3_BUCKET_UPLOADS, S3_BUCKET_ARTIFACTS (et autres buckets requis)

Ports

HOST_MINIO_API_PORT (API S3, par défaut 19500)
HOST_MINIO_CONSOLE_PORT (console, par défaut 19501)

Checks rapides

État service : docker compose ps minio
Console (local) : curl -I http://127.0.0.1:${HOST_MINIO_CONSOLE_PORT:-19501}/
Live probe (MinIO) : curl http://127.0.0.1:${HOST_MINIO_API_PORT:-19500}/minio/health/live

Reverse-proxy (si domaine public)

console-minio.votredomaine.tld doit proxy vers 127.0.0.1:${HOST_MINIO_CONSOLE_PORT:-19501}.
Si vous exposez aussi l’API S3 via un domaine dédié : proxy vers 127.0.0.1:${HOST_MINIO_API_PORT:-19500} et aligner MINIO_SERVER_URL.

Important : recharger la config

Toute modification .env liée à MinIO nécessite une recréation du conteneur : docker compose up -d --force-recreate minio
Si vous gérez les buckets via init : relancer minio-init : docker compose up -d --force-recreate minio-init

3) Erreurs fréquentes & correctifs

3.0 Installation / Wizard — erreurs courantes (serveur neuf)

A) pip install -r ops/requirements.txt → externally-managed-environment
Cause : protection PEP 668 (Python système).
Correctif (sans venv) :

sudo python3 -m pip install --break-system-packages -r ops/requirements.txt

Si un paquet Debian bloque (typing-extensions) :

sudo python3 -m pip install --break-system-packages --ignore-installed -r ops/requirements.txt

A2) ModuleNotFoundError: No module named 'typer'
Cause : dépendances wizard non installées.
Correctif :

pip install -r ops/requirements.txt

Sur Ubuntu/Debian récents :

sudo python3 -m pip install --break-system-packages -r ops/requirements.txt

B) Wizard : permission denied while trying to connect to the docker API
Cause : l’utilisateur n’a pas les droits sur /var/run/docker.sock.
Correctif :

sudo usermod -aG docker $USER
newgrp docker

ou relancer les commandes docker en sudo.

C) Console MinIO non accessible
Cause : pas d’entrée DNS pour console-minio.<domaine> ou Caddy incomplet.
Correctif : créer une entrée DNS A + bloc Caddy dédié (cf. docs/02_Installation/04-Checklist-Client.md).

D) Wizard redemandé / relance après échec
Relancer simplement :

python3 ops/install_wizard.py run

Mode rapide (ports & Docling par défaut) :

python3 ops/install_wizard.py run --fast

D2) Wizard en échec (préflight / validation / docker / healthcheck)
Le wizard affiche un bloc “PROMPT LLM (RECOVERY)”.
Copiez/collez‑le dans votre LLM : il contient les chemins vers le dossier de run, les logs JSONL et les artefacts utiles.
⚠️ Ne collez jamais de secrets dans la conversation : le LLM doit lire les fichiers localement sur le serveur.

E) Qdrant : Not existing vector name: dense
Symptôme : erreurs 500 côté API (ex. /api/admin/rag-assistant/recommend) avec un message Qdrant “not existing vector name: dense”.
Cause : la collection a été créée sans vecteur nommé, mais l’API interroge un vecteur dense dense (mode hybride attendu).

Option A — non destructrice (désactiver l’hybride)

Mettre l’hybride à false et vider le nom de vecteur :

sudo sed -i 's/^QDRANT_HYBRID_ENABLED=.*/QDRANT_HYBRID_ENABLED=false/' /etc/aurora/nexus.env
sudo sed -i 's/^QDRANT_DENSE_VECTOR_NAME=.*/QDRANT_DENSE_VECTOR_NAME=/' /etc/aurora/nexus.env

Recréer l’API / Gateway / Ingestion :

sudo AURORA_ENV_FILE=/etc/aurora/nexus.env docker compose --env-file /etc/aurora/nexus.env up -d --force-recreate api aurora_gateway ingestion

Option B — hybride (destructrice)
⚠️ Destructif : recrée la collection Qdrant → ré‑ingestion obligatoire.

Activer l’hybride :

sudo sed -i 's/^QDRANT_HYBRID_ENABLED=.*/QDRANT_HYBRID_ENABLED=true/' /etc/aurora/nexus.env
sudo sed -i 's/^QDRANT_DENSE_VECTOR_NAME=.*/QDRANT_DENSE_VECTOR_NAME=dense/' /etc/aurora/nexus.env

Recréer la collection Qdrant :

cd /home/ubuntu/Apps/Nexus
sudo AURORA_ENV_FILE=/etc/aurora/nexus.env docker compose --env-file /etc/aurora/nexus.env run --rm -v "$(pwd)/ops:/app/ops" api python /app/ops/recreate_qdrant.py

Relancer une ingestion complète des documents (UI Admin → Ingestion ou vos pipelines habituels).

3.1 Reset “documents uniquement” (environnement de test)

Si vous voulez repartir à zéro sans toucher aux utilisateurs / services / workspaces / settings, vous pouvez purger uniquement :

Postgres : tables documents + ingestion + artifacts
MinIO : objets des buckets uploads/artifacts
Qdrant : collection documents

Script : ops/purge_documents_only.sh

Exemples :

# Dev (utilise .env)
bash ops/purge_documents_only.sh

# Prod (env dans /etc/aurora)
sudo AURORA_ENV_FILE=/etc/aurora/nexus.env bash ops/purge_documents_only.sh

⚠️ Attention : destructive sur les documents. À n’utiliser que sur un environnement de test / staging.

E) Ingestion batch “failed” (Scraper) : BadRequestError embeddings 8192 tokens
Cause : certains contenus “monoligne” (HTML minifié) dépassent la limite tokens du modèle embeddings.
Correctifs possibles :

Mettre à jour Nexus (split des lignes longues au chunking).
Ou pré‑nettoyer les pages côté Scraper (wrap lignes longues).
Garder MAX_CHUNK_SIZE raisonnable (défaut 1000).

Symptôme :

Console navigateur : Gateway error puis openrouter 401 avec No cookie auth credentials found.

Cause la plus probable :

Clé OpenRouter invalide / placeholder dans les credentials tenant (en base), ou absence de credentials activées.
Clé Fernet (LLM_CREDENTIALS_ENC_KEY) incohérente avec les credentials BYOK chiffrés (clé changée → secrets illisibles).
Headers attendus par OpenRouter manquants (HTTP-Referer / X-Title) si PUBLIC_DOMAIN n’est pas renseigné.

Correctif :

UI Admin → Providers → Credentials :
- renseigner une vraie clé OpenRouter (tenant concerné)
- vérifier enabled
Vérifier que LLM_CREDENTIALS_ENC_KEY est la même que celle utilisée pour chiffrer les credentials.
Renseigner PUBLIC_DOMAIN (utilisé par le gateway pour HTTP-Referer/X-Title).

3.2 `GET /api/admin/providers/credentials` → 500 (Fernet)

Symptôme :

ValueError: Fernet key must be 32 url-safe base64-encoded bytes.

Cause :

LLM_CREDENTIALS_ENC_KEY invalide (format) ou incohérente par rapport aux données déjà chiffrées en base.

Correctif :

Restaurer la bonne valeur LLM_CREDENTIALS_ENC_KEY dans .env (celle utilisée lors du chiffrement initial).
Redémarrer api + aurora_gateway (et workers si nécessaires).

⚠️ Note : changer LLM_CREDENTIALS_ENC_KEY sans migration rend les credentials BYOK illisibles (et casse les appels LLM).

3.3 MinIO redémarre en boucle : `Invalid credentials` / “length should be…”

Symptôme :

Logs MinIO : MINIO_ROOT_PASSWORD length at least 8 characters

Cause :

Mot de passe MinIO trop court / vide dans .env.

Correctif :

Mettre un MINIO_ROOT_PASSWORD ≥ 8 caractères.
Recréer le service pour recharger l’env : docker compose up -d --force-recreate minio
Relancer la création des buckets : docker compose up -d --force-recreate minio-init

3.4 Postgres : `password authentication failed`

Cause :

Mot de passe dans .env ≠ mot de passe réel du rôle Postgres dans le volume.

Correctif :

Ré-aligner le mot de passe du rôle Postgres (ou remettre celui attendu par .env), puis redémarrer api/gateway.

3.5 “Je peux me connecter même si `ADMIN_DEFAULT_PASSWORD=change-me-now`”

Explication :

ADMIN_* sert au seed du compte admin au premier démarrage (si l’utilisateur n’existe pas).
Une fois l’utilisateur créé en base, le login utilise les données DB, pas le .env.

Symptôme :

Tentative de login UI → POST /api/auth/login retourne 401 Unauthorized malgré des identifiants “modifiés”.

Cause principale :

Le mot de passe admin est stocké en base.
ADMIN_EMAIL / ADMIN_DEFAULT_PASSWORD ne servent qu’au seed : ils ne mettent pas à jour un admin déjà existant.
Un simple docker compose restart ne recharge pas les variables d’environnement : il faut recréer les conteneurs.

Résolution :

Mettre à jour le mot de passe admin en base (UI si possible, ou via DB).
Recréer les conteneurs pour relire l’env :
```
docker compose up -d --force-recreate
```

Recommandations :

Documenter que changer ADMIN_DEFAULT_PASSWORD nécessite un up -d --force-recreate (pas un simple restart).
Ajouter un outil de reset admin (CLI ou endpoint sécurisé) pour mettre à jour le mot de passe en DB.
(Option) log explicite au boot si l’admin existe déjà et que l’env ne sera pas appliqué.

3.5ter Secrets “oubliés” / variables incohérentes

Symptôme :

Mot de passe Postgres oublié, ou valeurs attendues différentes de ce qui est en service.

Réflexe :

La source de vérité en production est /etc/aurora/nexus.env.
Si vous avez un nexus.env.full avec des placeholders (change-me-now), ne vous y fiez pas.

Attention :

Changer POSTGRES_PASSWORD dans l’env ne modifie pas le mot de passe existant dans la base si Postgres a déjà été initialisé.
Il faut mettre à jour le mot de passe en DB (ou recréer le volume si vous acceptez de perdre les données).

Après modification :

Recréer les conteneurs pour relire l’env :
```
docker compose up -d --force-recreate
```

3.5quater `ASSISTANT_CORE` manquant (erreur 500 sur `/api/admin/source-apps`)

Symptôme :

POST /api/admin/source-apps → 500
Erreur SQL : prompt_template_code = ASSISTANT_CORE mais template inexistant.

Cause :

Migrations de seed prompts non appliquées (ex. 29_CREATE_SERVICE_PROFILES.sql).
Très souvent : ops/init_db.sh lancé sans le bon env (il lisait .env et non /etc/aurora/nexus.env).

Correctif (idempotent) :

sudo AURORA_ENV_FILE=/etc/aurora/nexus.env bash ops/init_db.sh

Vérification :

sudo bash -lc 'set -a; source /etc/aurora/nexus.env; set +a; \
POSTGRES_CONTAINER=$(docker compose ps -q postgres); \
docker exec -i "$POSTGRES_CONTAINER" env PGPASSWORD="$POSTGRES_PASSWORD" \
  psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -tAc "select code from prompt_template where code=\"ASSISTANT_CORE\";"'

3.6 `GET /api/documents` ou `GET /api/ingest/batches` → 500 (Postgres) : `column "caller_app" does not exist`

Symptôme :

Les pages Documents / Ingestion ne chargent plus.
Logs API : psycopg2.errors.UndefinedColumn: column "caller_app" does not exist.

Cause :

Schéma Postgres trop ancien : migrations non appliquées (colonnes caller_app manquantes).

Correctif (recommandé) :

Rejouer les migrations idempotentes :
```
bash ops/init_db.sh
```
Vérifier ensuite :
- docker compose logs --tail=200 api (plus d’erreurs SQL)
  - UI : recharger Documents / Ingestion

3.7 Follow-ups “point B / point 2 / S2” ne fonctionnent pas (app externe)

Symptômes :

l’utilisateur demande “détaille le point B” / “détaille le point 2” et Nexus répond “je ne vois pas de point B” (ou tombe en clarification).
les réponses semblent “oublier” la structure du résumé précédent.

Explication :

“point B / point 2” référence souvent la structure de la réponse précédente, pas un titre présent dans le document.
Pour gérer ce cas de manière “enterprise safe” sans réinjecter l’historique brut, Nexus utilise :
- thread_id (identifiant stable par conversation)
- un bloc SUIVI en fin de réponse (machine‑parsable, non traduit)
- une table thread_state qui stocke un outline minimal (pas une source de faits).

Checklist de diagnostic :

Le client envoie bien thread_id à chaque POST /api/query (même valeur sur le fil).
Le client garde le même caller_app et le même utilisateur JWT sur la conversation.
Le service (prompt) termine bien les livrables par un bloc :
- SUIVI (exactement ce mot, non traduit)
- [S1] ... à [S4] ... (4 à 8 sections)
- aucun texte après le bloc.
Vérifier que la migration DB a été appliquée :
- bash ops/init_db.sh
Vérifier l’état thread_state :

SELECT updated_at, last_outline
FROM thread_state
WHERE caller_app = '<caller_app>' AND thread_id = '<thread_id>'
ORDER BY updated_at DESC
LIMIT 1;

Vérifier les logs du resolver :

SELECT created_at, question, followup_resolved, followup_section_id, followup_ref_type
FROM queries_log
WHERE caller_app = '<caller_app>' AND thread_id = '<thread_id>'
ORDER BY created_at DESC
LIMIT 10;

Attendu :

sur “détaille le point B” : followup_resolved=true, followup_section_id='S2'.
si l’utilisateur écrit “détaille ça” (anaphore pure) : Nexus doit proposer de choisir S1..S8 (sans appel LLM).

4) Bonnes pratiques (évite les incidents)

Ne jamais exécuter docker compose down -v sur un environnement contenant des données importantes.
Garder une sauvegarde sécurisée des secrets infra (LLM_CREDENTIALS_ENC_KEY, GATEWAY_INTERNAL_SECRET, identifiants DB/MinIO).
Documenter explicitement ce qui est attendu “en .env” vs “en base (UI Admin)”.

Troubleshooting — Aurora Nexus (MVP)

On this page