Fehlerbehebung
Symptomorientierte Lösungen für die Probleme, die wir wirklich sehen: ein blockiertes Widget, eine langsame erste Anfrage, Erkennungsfehler, Anreicherungsfehler und Anmeldeprobleme.
Starten Sie bei Ihrem Symptom. Jede Lösung auf dieser Seite ist das reale, heute ausgelieferte Mittel — und wenn ein Mensch gebraucht wird, sagt der letzte Abschnitt genau, wohin Sie schreiben.
Das Widget erscheint nicht
Die häufigste Ursache ist eine strenge Content-Security-Policy auf Ihrer Seite. Das Widget injiziert seine Styles per style-Element in sein Shadow DOM; eine style-src, die Inline-Styles verbietet, blockiert es — erlauben Sie 'unsafe-inline' unter style-src (die Styles verlassen das Shadow Root des Widgets nie). Die Browser-Konsole zeigt die CSP-Verletzung, wenn das die Ursache ist.
Prüfen Sie außerdem, dass script-src cdn.syncanix.com erlaubt (dort wird widget.js ausgeliefert) und connect-src api.syncanix.com (damit spricht es).
Seiten mit Trusted-Types-Erzwingung (require-trusted-types-for 'script') werden unterstützt: Das Widget startet und chattet, ohne eine String-Senke zu speisen. Nur wenn Ihre Richtlinie ZUSÄTZLICH die Richtliniennamen über eine trusted-types-Direktive einschränkt, erlauben Sie syncanix-widget (Bot-Schutz-Challenge), syncanix-widget-sw (Offline-Service-Worker) und dompurify (Antwort-Sanitizer) — andernfalls degradieren diese optionalen Funktionen kontrolliert, während der Chat weiter funktioniert.
Die erste Anfrage ist langsam oder schlägt einmal fehl und klappt dann
Auf ruhigen Workspaces kann die allererste Anfrage nach langer Inaktivität ein paar Sekunden dauern, während die Serverless-Kapazität aufwacht — in seltenen Fällen schlägt sie einmal fehl. Das Widget wiederholt das Laden seiner Konfiguration automatisch. Wenn Sie die API direkt aufrufen, behandeln Sie eine einzelne fehlgeschlagene erste Anfrage nach Inaktivität als wiederholbar.
Die Erkennung fand nichts oder wählte das falsche Framework
Führen Sie zuerst syncanix doctor aus — es prüft Node-Version, erkanntes Framework, Konfigurationsgültigkeit und API-Schlüssel in einem Durchgang. Lag die Erkennung daneben (gemischte Repos können sie verwirren), benennen Sie das Framework explizit: syncanix init --framework <name>.
Hat die Erkennung Ordner durchsucht, die sie nicht sollte (vendorter Code, generierte Dateien), tragen Sie sie in .syncanixignore ein und starten Sie erneut.
Die Anreicherung schlug fehl, oder Sie müssen offline arbeiten
Übergeben Sie --offline, um den Katalog lokal zu schreiben, ohne ihn hochzuladen; ohne konfigurierte Modellschlüssel schließt syncanix init --offline --yes die Erkennung ohne Anreicherung ab. Die Katalogdatei ist deterministisch — ein späterer Lauf wirbelt Ihre Durchsicht nicht durcheinander.
Anmeldeprobleme
syncanix login speichert ein im Dashboard erzeugtes Token in ~/.syncanix/credentials (nur für Sie lesbar); syncanix logout entfernt es. Schlagen Uploads mit einem Auth-Fehler fehl, führen Sie syncanix doctor aus — es sagt Ihnen, ob der gespeicherte Schlüssel auflöst — und melden Sie sich erneut an.
Eine gespeicherte Einwilligungsentscheidung ändern
Ihre Einwilligungsentscheidung zur Anreicherung liegt in .syncanix/consent.json. Zum Ändern löschen Sie die Datei und führen syncanix init erneut aus — die Einwilligungsabfrage erscheint wieder.