Troubleshooting
Kurz gesagt: Häufige Probleme und Lösungen — egal ob du Managed Hosting nutzt oder deinen eigenen Server betreibst. Fang hier an, wenn du nicht weiterkommst, Hilfe brauchst oder etwas kaputt ist.
Für wen das relevant ist
- Endnutzer auf Managed Hosting mit Billing- oder Capture-Problemen
- Operatoren, die Self-hosted-Deployment-, MCP- oder Verschlüsselungsprobleme debuggen
Managed-Nutzer
| Symptom |
Wahrscheinliche Ursache |
Lösung |
| Capture schlägt fehl — unzureichende Credits |
Gratis-Credits aufgebraucht oder kein aktives Abo |
Settings → LLM — abonnieren (3,99 €/Monat) oder BYOK konfigurieren |
| Capture schlägt fehl — LLM nicht konfiguriert |
Leeres Wallet (Plattform-Credits) oder fehlende BYOK-Keys |
Settings → LLM — abonnieren oder BYOK konfigurieren |
| Option zum Abonnieren/Billing fehlt |
Subscription-Checkout noch nicht aktiviert |
Support kontaktieren, BYOK nutzen oder selbst hosten |
| BYOK-Option deaktiviert |
Kein Provider unter Settings → LLM → BYOK hinterlegt |
Zuerst EUrouter- oder OpenRouter-Zugangsdaten speichern |
| Welcome-Tour erscheint nicht |
Bereits abgeschlossen oder übersprungen |
Settings → Onboarding → Onboarding neu starten |
| OAuth-Anmeldung schlägt fehl |
Provider auf diesem Deployment nicht aktiviert |
E-Mail/Passwort nutzen oder den Operator fragen |
Neu bei Eigen Mesh? Siehe Onboarding (Managed) oder Was ist Eigen Mesh?.
Deployment
| Symptom |
Wahrscheinliche Ursache |
Lösung |
| App-Container beendet sich beim Start |
BETTER_AUTH_SECRET, TENANT_MASTER_KEY oder LLM-Variablen fehlen |
Erforderliche Umgebungsvariablen setzen |
| Datenbankverbindung wird verweigert |
db-Container noch nicht bereit oder falsche DATABASE_URL |
Auf Health warten; innerhalb von Compose postgres://eigen:eigen@db:5432/eigen verwenden |
| 500 bei erster Anfrage nach dem Deploy |
Schema oder RLS nicht angewendet |
Im eigen-Repository npm run db:push:force && npm run db:rls ausführen |
| Coolify-Deploy grün, App liefert aber 502 |
Migrationen nicht ausgeführt |
Execute Command auf dem App-Container: npx drizzle-kit push --force && node scripts/apply-rls.mjs |
| Postgres-Port-Konflikt auf dem Host |
Standard-Mapping 5432:5432 |
Ports in docker-compose.yaml ändern |
LLM und Billing
| Symptom |
Wahrscheinliche Ursache |
Lösung |
| Capture schlägt fehl — LLM nicht konfiguriert |
Leeres Wallet (Plattform-Credits), kein Abo oder fehlende BYOK-Keys |
Settings → LLM — abonnieren, Credits aufladen (Self-hosted-Operator) oder BYOK konfigurieren |
| Alle LLM-Aufrufe schlagen nach 3 Retries fehl |
Gateway nicht erreichbar, falsche LLM_BASE_URL oder ungültige Rule-UUIDs |
Gateway-Zugangsdaten sowie LLM_RULE_CHAT / LLM_RULE_EMBEDDING prüfen |
| PayPal-Button fehlt (Self-hosted Wallet-Aufladung) |
PAYPAL_*-Env-Variablen nicht gesetzt |
PayPal für Operator-Credit-Pakete konfigurieren oder Nutzer auf BYOK umstellen |
| BYOK-Option deaktiviert |
Kein Provider unter Settings → LLM → BYOK hinterlegt |
Zuerst EUrouter- oder OpenRouter-Zugangsdaten speichern |
MCP-Integration
| Symptom |
Wahrscheinliche Ursache |
Lösung |
| 401 Unauthorized |
Ungültiger oder widerrufener API-Key |
Unter /api-keys neu generieren; Client-Konfiguration aktualisieren |
| Tools erscheinen nicht im Client |
MCP-Server deaktiviert oder falsche URL |
https://<origin>/api/mcp prüfen — siehe Cursor oder Claude verbinden |
| Leere Suchergebnisse |
Noch keine Thoughts erfasst oder Query zu eng |
Test-Thoughts erfassen; breitere Queries ausprobieren |
| Connection refused (lokal) |
App läuft nicht auf dem erwarteten Port |
docker compose ps prüfen; Standardport 3000 |
Auth und Verschlüsselung
| Symptom |
Wahrscheinliche Ursache |
Lösung |
| OAuth-Anmeldung schlägt fehl |
Callback-URL stimmt nicht überein |
Muss {ORIGIN}/api/auth/callback/<provider> sein |
| Ver-/Entschlüsselungsfehler |
TENANT_MASTER_KEY fehlt oder wurde ohne Migration rotiert |
Siehe Tenant-Envelope-Verschlüsselung |
| Neue Nutzer funktionieren, alte nicht |
Key-Rotation ohne Migration |
Key wiederherstellen oder Re-Encryption-Migration ausführen |
Retrieval
| Symptom |
Wahrscheinliche Ursache |
Lösung |
| Unerwartetes Ranking |
Retrieval nutzt gewichtetes Merge + LLM-Rerank über vorberechnete Nachbarn |
Spezifischere Query versuchen; Treffer mit retrieve_thoughts inspizieren |
| Fundierte Antwort trifft den Kontext nicht |
Query passt nicht zum gespeicherten Wortlaut |
Vor dem Formulieren retrieve_thoughts mit anderer Formulierung versuchen |
| Fragen auf Themenebene schwach |
Globales Retrieval zurückgestellt |
Für die MVP erwartbar — korpusweite Synthese ist nicht angebunden |
Immer noch nicht weiter?
- Prüfe Activity in der Produkt-UI für Fehlerdetails pro Aufruf.
- Sieh dir die App-Container-Logs an:
docker compose logs app
- Sieh dir die DB-Logs an:
docker compose logs db
- Siehe Upgrades & Backups, bevor du destruktive Änderungen vornimmst.
Nächste Schritte
