FAQ et dépannage
Vérifié avec Cortex le 2 octobre 2026
Cette page réunit les questions fréquentes sur Cortex et les solutions aux problèmes courants d’installation et de configuration.
Questions fréquentes
Cortex envoie-t-il des données à Wavertex?
Nous n’avons trouvé aucune télémétrie, analytique, vérification de mises à jour ni appel de type « phone-home » dans le code de la passerelle, de l’interface web et du moteur IA (version vérifiée le 5 octobre 2026). À l’exécution, les seules connexions sortantes vont vers des services que vous configurez : les destinations LLM (elles reçoivent le message déjà caviardé), votre fournisseur d’identité OIDC ou SAML, le moteur de recherche web et le moteur IA s’ils sont activés, et les serveurs d’inférence et d’embeddings du moteur IA. La commande d’administration pricing:sync ne récupère les prix en ligne que si vous lui passez --online; sans cet argument, elle lit un instantané des prix fourni avec le dépôt. Le point de mesure /metrics répond seulement si vous définissez METRICS_TOKEN, et c’est à votre outil de supervision de l’interroger. L’interface web est construite et démarrée avec la télémétrie anonyme de Next.js désactivée (NEXT_TELEMETRY_DISABLED=1). Une réserve : dans les conteneurs Cortex, chaque commande pnpm (le démarrage de l’interface web, ou une commande d’administration comme pricing:sync lancée dans un conteneur) interroge le registre public npm pour vérifier la version de pnpm fixée par le projet; sans accès à ce registre, la commande aboutit quand même, mais une à deux minutes plus tard dans nos essais.
Cortex fonctionne-t-il sans le moteur IA?
Oui. Le moteur IA est facultatif : sans lui, le filtrage DLP par motifs et par secrets continue de s’appliquer, et aucune fonction essentielle n’en dépend. Il ajoute la reconnaissance de noms (DLP 1.5), la détection par modèle local (DLP 2) et l’extraction et les embeddings de la base de connaissances. Voir Installation pour l’activer.
Quels modèles sont pris en charge?
Cortex se connecte aux fournisseurs du catalogue (openai, anthropic, azure_openai, google_gemini, mistral, groq, together_ai, openrouter, deepseek, xai) et aux moteurs locaux (ollama, lm_studio, vllm), ainsi qu’à tout service compatible via custom_openai, custom_anthropic ou custom_local. Vous choisissez les modèles autorisés pour chaque destination. Voir Fournisseurs et modèles.
Un profil DLP « allégé » réduit-il le filtrage?
Pas aujourd’hui. Le profil d’une destination est une étiquette : la passerelle la consigne au journal d’audit et l’affiche, mais le code n’en tire aucune différence de traitement. L’analyse DLP s’applique de la même façon à toutes les destinations. La console réserve « Profil allégé » au réseau privé et exige une approbation pour une adresse qui ne l’est pas (voir Règles DLP).
Dépannage
Un réglage de .env semble ignoré. Pourquoi?
Un conteneur ne reçoit une variable que si docker-compose.yml la liste dans son bloc environment:. Les variables marquées « Hôte seulement » dans .env.example n’y sont pas : les modifier ne change rien dans les conteneurs. Ajoutez la variable au bloc environment: du service, ou lancez le processus sur l’hôte avec la valeur. Les commandes pnpm --filter gateway … ne lisent pas .env non plus; seul le raccourci pnpm migration:run de la racine le lit. Voir Configuration.
Le moteur IA est signalé comme indisponible. Que se passe-t-il?
La passerelle sonde le moteur toutes les 30 secondes. Si elle ne l’atteint pas, elle le signale comme indisponible dans ses capacités, sans erreur pour les employés, et les requêtes continuent avec le DLP 1 seul. Quand un appel de détection échoue ou dépasse son délai, une entrée « Requête envoyée avec DLP 1 seul (moteur IA dégradé) » est ajoutée au journal d’audit. Vérifiez que AI_ENGINE_URL est une origine (schéma, hôte, port, sans chemin) que le conteneur de la passerelle peut joindre, et que le moteur tourne.
Des documents restent en attente. Que vérifier?
La carte « Posture de la base de connaissances » donne la raison : moteur IA qui ne répond pas, ou aucun modèle d’embedding déclaré. Dans les deux cas, les téléversements attendent dans la file et sont traités dès que la situation se règle; si le moteur est désactivé dans la configuration, ils sont refusés. Vérifiez aussi que RAG_INGEST_INTERVAL_MS n’est pas à 0 : cette valeur désactive le traitement et les documents restent « Téléversé ». Voir Base de connaissances.
Je ne peux pas rester connecté en accédant à Cortex en http par une adresse du réseau local. Pourquoi?
Les images de Cortex démarrent en mode production, et la passerelle marque alors le cookie de session « Secure ». La plupart des navigateurs refusent de conserver un tel cookie sur une connexion http non chiffrée, sauf sur localhost. Servez Cortex en HTTPS (derrière un mandataire inverse) plutôt qu’en http sur une adresse IP du réseau.
Toutes les routes de l’API répondent 500 après docker compose up.
docker compose up démarre les conteneurs sans jamais exécuter les migrations : le schéma n’existe pas encore. C’est voulu. Exécutez la séquence de migration et de provisionnement de la première installation avant de vous connecter.
Erreur « tenant key mismatch » ou 500 au premier message après le provisionnement.
La valeur de KMS_LOCAL_KEK utilisée pour la commande de provisionnement diffère de celle de la passerelle en marche, qui ne peut alors pas déchiffrer la clé du locataire. Relancez le provisionnement avec la même valeur que celle du service gateway.
migration:run échoue avec « password authentication failed for user "cortex_owner" ».
Les commandes pnpm --filter gateway … lisent la configuration de leur seul environnement, pas .env (le raccourci pnpm migration:run de la racine, lui, le lit). Mettez dans MIGRATION_DATABASE_URL le mot de passe que le rôle possède réellement : celui de CORTEX_OWNER_PASSWORD au moment où le volume a été initialisé pour la première fois. Modifier .env plus tard ne change pas le mot de passe d’un rôle existant.
Un port est déjà utilisé.
Un des ports publiés est occupé sur l’hôte : 3000 (web), 4000 (passerelle), 5432 (PostgreSQL) ou 8080 (Keycloak, profil sso). Libérez-le, ou changez-le avec WEB_PORT, GATEWAY_PORT, POSTGRES_PORT ou KEYCLOAK_PORT dans .env avant de relancer docker compose up -d.