Aurora Nexus
Aurora NexusOperations

Troubleshooting — Aurora Nexus (MVP)

(depuis `TROUBLESHOOTING.md`)

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://rag.auroramind.fr)

2.1 Checklist MinIO “OK”

Objectif : la console MinIO est accessible via son domaine public (ex. https://console-minio.auroramind.fr/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.auroramind.fr (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.auroramind.fr doit proxy vers 127.0.0.1:${HOST_MINIO_CONSOLE_PORT:-19501}.
  • Si vous exposez aussi l’API S3 via un domaine (ex. minio.auroramind.fr) : 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.1 POST /api/query → 500 + No cookie auth credentials found (OpenRouter)

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.

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 :

  1. Le client envoie bien thread_id à chaque POST /api/query (même valeur sur le fil).
  2. Le client garde le même caller_app et le même utilisateur JWT sur la conversation.
  3. 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.
  4. Vérifier que la migration DB a été appliquée :
    • bash ops/init_db.sh
  5. 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;
  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)”.

Licences & conformité (AGPL‑3.0 + dépendances)

licence AGPL‑3.0 + conformité dépendances (process)

Backup / Restore — Aurora Nexus (MVP Safe)

(depuis `BACKUP_RESTORE.md`)

On this page

1) Sources de vérité (important)A) Configuration “Infra” (dans .env à la racine)B) Configuration “Métier” (en base Postgres via l’UI Admin / API)2) Checklist “stack OK”2.1 Checklist MinIO “OK”3) Erreurs fréquentes & correctifs3.1 POST /api/query → 500 + No cookie auth credentials found (OpenRouter)3.2 GET /api/admin/providers/credentials → 500 (Fernet)3.3 MinIO redémarre en boucle : Invalid credentials / “length should be…”3.4 Postgres : password authentication failed3.5 “Je peux me connecter même si ADMIN_DEFAULT_PASSWORD=change-me-now”3.6 GET /api/documents ou GET /api/ingest/batches → 500 (Postgres) : column "caller_app" does not exist3.7 Follow-ups “point B / point 2 / S2” ne fonctionnent pas (app externe)4) Bonnes pratiques (évite les incidents)