Dépannage
Des solutions par symptôme pour les problèmes que nous voyons réellement : un widget bloqué, une première requête lente, des ratés de détection, des échecs d’enrichissement et des soucis de connexion.
Partez de votre symptôme. Chaque solution de cette page est le remède réel, livré aujourd’hui — et quand il faut un humain, la dernière section dit exactement où écrire.
Le widget n’apparaît pas
La cause la plus fréquente est une Content-Security-Policy stricte sur votre page. Le widget injecte ses styles dans son Shadow DOM via un élément style ; une style-src qui interdit les styles en ligne le bloque — autorisez 'unsafe-inline' sous style-src (les styles ne sortent jamais du shadow root du widget). La console du navigateur affiche la violation CSP quand c’est la cause.
Vérifiez aussi que script-src autorise cdn.syncanix.com (qui sert widget.js) et que connect-src autorise api.syncanix.com (avec qui il dialogue).
Les pages qui appliquent Trusted Types (require-trusted-types-for 'script') sont prises en charge : le widget démarre et converse sans alimenter aucun puits de chaînes. Seulement si votre politique restreint AUSSI les noms de politiques via une directive trusted-types, autorisez syncanix-widget (défi anti-bots), syncanix-widget-sw (service worker hors ligne) et dompurify (assainisseur de réponses) — sinon ces fonctions optionnelles se dégradent proprement et le chat continue de fonctionner.
La première requête est lente, ou échoue une fois puis fonctionne
Sur les espaces de travail calmes, la toute première requête après une longue inactivité peut prendre quelques secondes le temps que la capacité serverless se réveille et, rarement, échoue une fois. Le widget réessaie automatiquement le chargement de sa configuration. Si vous appelez l’API directement, traitez comme réessayable une unique première requête en échec après inactivité.
La découverte n’a rien trouvé, ou s’est trompée de framework
Lancez d’abord syncanix doctor : il vérifie votre version de Node, le framework détecté, la validité de la configuration et la clé d’API en une passe. Si la détection s’est trompée (les dépôts mixtes peuvent la perturber), nommez le framework explicitement : syncanix init --framework <nom>.
Si la découverte a parcouru des dossiers qu’elle n’aurait pas dû (code vendorisé, fichiers générés), ajoutez-les à .syncanixignore et relancez.
L’enrichissement a échoué, ou vous devez travailler hors ligne
Passez --offline pour écrire le catalogue localement sans l’envoyer ; sans clés de modèle configurées, syncanix init --offline --yes termine la découverte sans enrichissement. Le fichier du catalogue est déterministe : relancer plus tard ne bouscule pas votre relecture.
Problèmes de connexion
syncanix login stocke un jeton généré dans le tableau de bord dans ~/.syncanix/credentials (lisible par vous seul) ; syncanix logout le supprime. Si les envois échouent avec une erreur d’authentification, lancez syncanix doctor — il vous dit si la clé stockée se résout — puis reconnectez-vous.
Modifier une décision de consentement enregistrée
Votre décision de consentement à l’enrichissement est stockée dans .syncanix/consent.json. Pour la changer, supprimez le fichier et relancez syncanix init : l’invite de consentement s’affiche à nouveau.