Dépannage

Cette page recense les pannes et messages d’erreur les plus courants dans Abra, classés par domaine. Format : Symptôme → Cause → Solution, pour aller droit au but. Elle complète la FAQ : la FAQ répond au « comment faire… ? », cette page au « pourquoi X échoue / que veut dire l’erreur Y ? ». Utilisez la recherche (en haut) ou dépliez le domaine concerné.

Avant tout diagnostic : rechargez la page, et notez le message exact (au survol d’un badge, dans le toast, ou dans la console du navigateur). Pour les erreurs API, conservez l’en-tête X-Request-Id de la réponse : il permet au support de retrouver l’incident dans les logs.

Connexion & accès

Symptôme	Cause probable	Solution
Aucun bouton de connexion ne correspond à mon compte	L’admin n’a activé que certaines méthodes (mot de passe, SSO, Google/Microsoft)	Demandez à l’administrateur de votre organisation quelle méthode utiliser — lui seul active chaque option
Le lien d’invitation ne fonctionne plus / a expiré	Invitation périmée ou déjà utilisée	Demandez une nouvelle invitation à l’admin
Après SSO, je n’arrive pas dans la bonne organisation	Le rattachement se fait par le domaine de l’e-mail ; le vôtre n’est pas mappé	Signalez-le à l’admin / à l’opérateur : le domaine doit pointer vers votre organisation
Un bouton est grisé ou une page a disparu (Gestion, Gouvernance LLM, Studio…)	L’interface s’adapte à votre rôle — ce n’est pas un bug	Ces entrées sont réservées aux rôles manager / admin. Demandez les droits à votre admin
Je ne vois aucun agent dans une organisation neuve	Rien n’a encore été activé	Ouvrez la Marketplace et activez un agent ; s’il n’y a pas de catalogue, l’admin doit en publier

SSO qui ne redémarre pas / méthode absente. La configuration SSO (Entra, Google) se met en place avec l’opérateur de l’instance — l’application d’identité est partagée. Un membre ne peut pas l’activer lui-même.

Connecteurs & OAuth

Symptôme	Cause	Solution
`redirect_uri_mismatch` à la connexion OAuth	L’URL de redirection n’est pas déclarée à l’identique chez le fournisseur	Copiez l’URL exacte depuis Abra (dialogue OAuth, ou bouton « i » de la carte) et collez-la dans Authorized redirect URIs de l’app (Google/Azure/Slack)
Bouton « Se connecter » absent ou « Fournisseur non configuré »	L’organisation n’a pas encore déclaré l’application OAuth (client ID + secret)	Réservé à l’admin : il configure le connecteur, puis la carte passe à Disponible
Badge « Non configuré » (ambre) sur un connecteur	Rien n’est branché pour ce service	L’admin colle la clé API ou l’application OAuth. Un membre ne saisit jamais de secret
Clé API refusée / service qui répond « 401/403 » côté fournisseur	Clé invalide, expirée, ou droits insuffisants sur la clé	L’admin ressaisit une clé valide dans Configurer (les champs secrets restent vides = « laisser vide pour conserver »)
Un service Google/Microsoft n’apparaît pas comme connecté alors que j’ai configuré le voisin	C’est voulu : une app couvre toute la famille	Le connecteur hérite (badge bleu Hérité). Reliez votre compte sur la carte concernée, l’app est déjà là
L’accès OAuth « saute » régulièrement	Déconnexion, ou révocation côté fournisseur	Recliquez Se connecter. Rien n’est supprimé chez le fournisseur — la reconnexion est immédiate

Où trouver l’URL de redirection. Dialogue de configuration OAuth (encadré redirect URIs, bouton copier) et bouton « i » de la carte du connecteur. Détails : Connecter des outils.

Agents & réponses

Symptôme	Cause	Solution
L’agent n’utilise pas ses connaissances (réponse générique, aucune source citée)	Documents pas au statut Prêt, ou outil de recherche documentaire désactivé	Vérifiez que les documents sont Prêt ; activez l’outil RAG dans la section Outils du constructeur d’agent
L’agent cite la mauvaise source	Documents qui se recoupent ou se contredisent	Dédoublonnez : gardez une version de référence par sujet
L’agent invente une réponse	Garde-fou insuffisant dans le prompt système	Ajoutez la consigne « appuie-toi sur les documents, sinon dis je ne sais pas »
Erreur `402` / « budget atteint » en pleine conversation	Budget LLM de l’org ou quota du membre épuisé (`LLM_BUDGET_EXHAUSTED`)	Un admin doit relever le budget/quota, ou attendre le reset du mois
Le modèle voulu n’apparaît pas dans la liste	L’admin ne l’a pas mis dans l’allowlist (intersection org × plateforme)	Demandez à l’admin d’autoriser le modèle. Un modèle hors liste ne peut pas être choisi
L’agent répond « je ne peux pas accéder à vos e-mails / agenda »	Aucun connecteur branché, ou outil non autorisé pour l’agent	Reliez le connecteur OAuth et autorisez l’outil dans le constructeur d’agent

Voir Donner des connaissances (RAG) et Créer un agent.

API (Agents-as-API)

Codes renvoyés par /api/v1/agents/.... Toutes les erreurs sont au format { "error": "…", "requestId": "…" } (hors flux SSE).

Code	Signification	Cause	Solution
`400`	Corps invalide	`message`/`messages` manquant ou vide, ou dernier message non-`user`	Fournissez soit `message` (chaîne non vide) soit `messages` (tableau non vide, finissant par un message `user`)
`401`	`Invalid API key`	Clé absente, invalide, révoquée ou expirée	Vérifiez l’en-tête `Authorization: Bearer abra_live_…` (ou `x-api-key`). Clé révoquée = créez-en une nouvelle (le secret ne s’affiche qu’une fois)
`402`	`Monthly cap exceeded`	Plafond mensuel de la clé, ou budget LLM de l’org (`LLM_BUDGET_EXHAUSTED`)	Attendez le reset (début du mois UTC) ou faites relever le plafond par un admin. Ne réessayez pas en boucle
`403`	Accès refusé	Clé sans principal, agent non autorisé pour la clé, ou modèle hors allowlist (`AGENT_TEMPLATE_MODEL_NOT_ALLOWED`)	Vérifiez le périmètre de la clé (agents autorisés) et n’utilisez `model` que dans l’allowlist
`404`	Introuvable	Agent en brouillon/rejeté (seuls les approuvés sont exposés), thread inexistant, ou API désactivée (`AGENTS_API_ENABLED=false`)	Approuvez/publiez l’agent ; pour l’activation de l’API, voyez l’opérateur de l’instance
`429`	`Rate limit exceeded`	Débit dépassé (défaut 60 req/min, fenêtre glissante)	Respectez l’en-tête `Retry-After` (secondes) et prévoyez un backoff
`503`	Provider indisponible	Fournisseur ou clé LLM non configurés sur l’instance	L’admin doit configurer le fournisseur IA dans les Connexions

Mon appel navigateur est bloqué (CORS). Par défaut une clé est serveur-à-serveur : aucun en-tête CORS n’est renvoyé. Ajoutez l’origine exacte de votre page (ex. https://app.mon-site.com) dans les Domaines autorisés de la clé. Abra reflète cette origine — jamais *. Une origine non listée reçoit une réponse sans en-tête CORS et le navigateur bloque la lecture. Voir Référence API.

Clé perdue. Impossible à récupérer (seul un hash est stocké) : créez-en une nouvelle et révoquez l’ancienne.

Documents / RAG

Symptôme	Cause	Solution
Document bloqué en « Traitement » longtemps	L’indexation prend en général quelques secondes ; un gros fichier peut être plus long	Patientez, la liste se rafraîchit seule. Si ça ne finit jamais, voir la ligne « Erreur » ci-dessous
Document en « Erreur », ne devient jamais « Prêt »	Cause n°1 : aucun modèle d’indexation choisi pour l’org (réglage admin à faire une seule fois)	Passez la souris sur le badge pour lire le message ; si ça parle de configuration, l’admin doit choisir un modèle d’embedding
Document en « Erreur » (autres cas)	Fichier corrompu, ou scan d’image sans texte lisible	Redéposez un PDF à vrai texte (mots sélectionnables), pas un scan image
Format refusé au dépôt	Type non supporté	Formats acceptés : PDF (vrai texte), `.docx`, `.txt`, `.md`, CSV, HTML, JSON. Images / PDF scannés = non exploitables
Dépôt refusé (fichier trop lourd)	Limite de 25 Mo par fichier	Découpez le document en plusieurs fichiers thématiques (meilleur pour la précision, aussi)
L’agent par défaut ne trouve pas un document d’organisation	Limite actuelle : l’agent par défaut interroge surtout votre base personnelle	Pour un savoir partagé, créez un agent dédié et attachez-lui les documents

Voir Donner des connaissances (RAG).

Workflows & automatisations

Symptôme	Cause	Solution
Exécution en statut « Erreur »	Le plus souvent, un connecteur manquant ou déconnecté	Ouvrez l’Historique → le passage concerné : données d’entrée + message d’erreur. Reliez l’outil, puis relancez
Un workflow demande de connecter un outil à l’activation	Il a besoin d’un service (Google, CRM, base…) et aucun compte relié ne correspond	Connectez le compte proposé dans la fenêtre, puis réessayez — sans quitter l’activation
Une automatisation ne se déclenche pas	Son interrupteur n’est pas allumé	Activez l’automatisation ; elle tournera ensuite selon son planning / événement
Après suppression d’un accès connecteur, des workflows échouent	L’accès (credential) qu’ils utilisaient a été retiré	Rechoisissez un autre accès dans le sélecteur de credential du workflow
Un modèle activé ne trouve pas mes réglages / mon historique	Chaque activation crée votre copie personnelle, isolée	Normal : vos lancements et votre historique vous sont propres et ne sont pas partagés

Voir Workflows & automatisations.

Toujours bloqué ? Reprenez le sujet dans son guide dédié (chaque guide finit par ses propres questions fréquentes) ou consultez la FAQ. Pour une erreur API, donnez le X-Request-Id au support. Sinon, contactez l’administrateur de votre organisation — et, pour une instance auto-hébergée, votre interlocuteur Abra.