troubleshooting

Customer Service Portal · Startseite · Installation · Konfiguration · Betrieb

---

Fehlerbehebung

Symptom	Prüfung und Abhilfe
Build meldet ungültige öffentliche Konfiguration	CSP_NAME, Hotline, sechsstellige Hex-Farben und Basispfad prüfen. Hex-Farben in .env in Anführungszeichen setzen. Leere GitHub-Build-Variablen überschreiben lokale Werte.
API startet nach Plugin-Installation nicht	Erforderliche Runtime-Werte am API-Host setzen. Alle installierten Plugin-Schemas werden vor dem Start validiert.
Frontend lädt, API bleibt unerreichbar	CSP_API_URL ohne /api/v1, HTTPS, tatsächliche API-Adresse und CSP_ALLOWED_ORIGINS prüfen. Build und API-Runtime getrennt konfigurieren.
Pages zeigt fehlende Assets oder falsche Links	CSP_BASE_PATH=/<repo>/ bei Repo-Pages verwenden; führender/abschließender Slash nötig. Logo-/Avatar-URLs müssen den Pfad enthalten. Neu bauen und deployen.
Branding-Änderung erscheint nicht	Repository-Variablen werden nur über explizite Workflow-Zuordnungen übernommen. Neues Deployment prüfen; bei bestehender PWA neu laden und Service-Worker-Stand kontrollieren.
Live-Daten sind veraltet, obwohl /health grün ist	Installierte Provider-Routen prüfen und stale/error auswerten. Health prüft nur den Prozess. Providerrechte, URL, Team-ID/Slug und ausgehende Erreichbarkeit prüfen.
SIGNL4-Team oder Schichten fehlen	API-Key mit Leserechten, korrektes Team und vollständige Providerantwort prüfen. Deaktivierte Mitglieder und abgelaufene/ungültige Schichten werden gefiltert.
Avatar fehlt	Demo zeigt Initialen. Produktiv Teammitgliedschaft, Bildrechte und erlaubten Bildtyp prüfen. Bilder über 2 MiB werden abgelehnt.
Kuma zeigt unbekannten Status	Statusseite muss veröffentlicht sein. URL und Slug prüfen; fehlende oder veraltete Heartbeats nicht als aktuelle Verfügbarkeit behandeln.
Chat meldet 400	Letzte Rolle user, 1–20 Nachrichten, höchstens 4000 Zeichen pro Nachricht/16000 insgesamt und keine zusätzlichen JSON-Felder verwenden.
Chat meldet 429	IP- oder Prozess-Parallelitätslimit erreicht; Retry-After beachten. Proxy-Konfiguration prüfen, wenn alle Nutzer dieselbe IP erhalten.
Chat erreicht Ollama im Container nicht	localhost ist der Container selbst. Eine vom API-Container erreichbare Ollama-URL und installiertes Modell konfigurieren.
Chat-Text erscheint erst am Ende	SSE-Buffering am Reverse-Proxy deaktivieren und Streaming-Zeitlimits prüfen.
Inhalte in UI und Chat weichen ab	Dieselbe content.json im Frontend-Build und API-Deployment verwenden; Frontend neu bauen und API neu starten.
CLI lehnt Plugin-Mutation ab	Kundenrepo außerhalb eines übergeordneten pnpm-Workspaces verwenden. Paketmetadaten, SDK-Kompatibilität und erforderliche Plugin-IDs prüfen.
Paketversionen oder Plugin-SDK passen nicht	Gemeinsame Release-Version der Produktpakete verwenden; Dependency-/Lockfile-Stand prüfen und beide Anwendungsteile neu bauen.
npm-Publish scheitert	NPM_AUTH_TOKEN mit Scope-/Paketschreibrechten und Recht zur Erstveröffentlichung prüfen. Workflow mit publish_tag erneut ausführen; siehe Betriebsdokumentation.
Wiki-Abgleich scheitert	Wiki unter Repository-Settings aktivieren, erste Seite manuell speichern und die contents: write-Berechtigung des automatischen GITHUB_TOKEN prüfen. Tag muss docs/ enthalten; ältere Tags mit Docs/ werden ebenfalls unterstützt. Details unter Dokumentation und Wiki.

Fehlerberichte sollten Paketversionen, betroffene Plugin-ID, API-Status/Datenzustand, reproduzierbare Schritte und bereinigte Workflow-/Browsermeldungen enthalten. Keine Provider-Schlüssel oder vertraulichen Gesprächsinhalte in öffentliche Issues aufnehmen.

Weiter: API, Betrieb und Releases, Dokumentation und Wiki.