entrytwo
kaufen

docs / troubleshooting / common-issues.md

Fehlerbehebung & häufige Probleme

Diese Seite sammelt praktische Probleme und wie du sie löst.

Nutze den In-App-Chat oder ein externes Modell mit geladenen Docs für kontextspezifischere Hilfe.

Erster Admin / Bootstrap-Probleme

„No admin exists“ oder ständige Umleitung zur Admin-Erstellung

  • Auf einer komplett frischen Datenbank erwartet.
  • Sicherstellen, dass die erste Benutzererstellung geklappt hat (Browser-Konsole oder Server-Logs).
  • Lokale Entwicklung: Sofort-E-Mail über /api/auth/dev (kein SMTP).
  • Produktion: Zuerst SMTP und/oder OAuth; danach Magic Link oder Google/Microsoft. Sofort-E-Mail liefert 403.
  • Nach dem ersten ADMIN sollte dieser Screen nicht wieder erscheinen.

Bootstrap-Formular tut nichts oder Fehler

  • Prüfen, ob die Datenbank erreichbar ist (DATABASE_URL korrekt).
  • Migrationen: in Produktion/Docker npx prisma migrate deploy (migrate dev nur lokal ohne Docker).
  • Server-Logs auf Prisma- oder Auth-Fehler prüfen.

Anmeldung / OAuth / Magic Link

OAuth-Buttons fehlen

  • GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET und/oder Microsoft-Entra-ID-Paar setzen und App neu starten.
  • Redirect-URIs registrieren: {AUTH_URL}/api/auth/callback/google und .../microsoft-entra-id.

Zugriff verweigert nach OAuth

  • Neue Benutzer brauchen eine aktive Einladung für genau diese E-Mail (nach dem Bootstrap).
  • Die Google-/Microsoft-Konto-E-Mail muss zur Einladung passen (Groß-/Kleinschreibung egal).
  • Deaktivierte Benutzer können sich nicht anmelden.

Magic Link kommt nicht / ist ungültig

  • Volles SMTP-Trio: SMTP_HOST, SMTP_USER, SMTP_PASS (plus SMTP_FROM und AUTH_URL).
  • Links laufen nach 30 Minuten ab und sind einmalig; ein neuer Link macht den vorherigen ungültig.
  • Spam prüfen; AUTH_URL muss zur öffentlichen HTTPS-Origin passen.

Abmelden geht nicht

  • Einstellungsmenü (Zahnrad) → Abmelden.

Produktions-Health wegen Auth degraded

  • GET /api/health sollte auth.productionReady: true zeigen.
  • Nötig: starkes AUTH_SECRET, AUTH_URL, AUTH_TRUST_HOST=true und mindestens eines von SMTP / Google / Microsoft.

HTTPS / SSL-Fehler im Browser

  • A-Record der Domain muss auf die VPS-IP zeigen (dig +short deine.domain).
  • Let’s Encrypt funktioniert erst mit öffentlichem DNS. Bei zu frühem Zertifikatsversuch Reverse-Proxy neu starten (z. B. systemctl restart caddy).
  • Die App kann auf localhost:3000 gesund sein, während HTTPS noch scheitert.

Docker: Migration „datasource.url property is required“

  • Image muss prisma.config.ts enthalten (Prisma 7). Mit aktuellem Dockerfile neu bauen.
  • Runtime braucht DATABASE_URL.

Docker-Build: AUTH_SECRET required in production

  • Aktuelle Dockerfiles setzen einen Build-Platzhalter. Neu bauen; Runtime-.env muss ein echtes AUTH_SECRET setzen.

SSH Permission denied (publickey)

  • Ein Key in der Cloud-Konsole liegt nicht automatisch auf der VM. Public Key in /root/.ssh/authorized_keys legen oder Server mit ausgewähltem Key neu anlegen.

Datenbank / Verbindungsprobleme

„Error: P1001: Can't reach database server“

  • Postgres läuft nicht oder Host/Port in DATABASE_URL sind falsch.
  • Mit Docker Compose: db-Service healthy halten (docker compose ps, docker compose logs db).
  • Häufiger Fix: Service-Name db von innerhalb des App-Containers, oder localhost vom Host aus.

Seed scheitert oder Unique-Constraint-Fehler

  • Oft bedeutet das, dass schon Teildaten existieren.
  • Sicherer Reset (nur Entwicklung): npx prisma migrate reset, dann npm run db:seed.

Prisma-Client veraltet nach Schema-Änderung

  • npx prisma generate ausführen.

Chat / KI funktioniert nicht

Chat antwortet mit Text, erzeugt aber nie Buchungen oder Vorschläge

  • Kein LLM-Key konfiguriert oder falscher Provider/Modell.
  • .env prüfen: NEXT_LLM_PROVIDER, NEXT_LLM_MODEL und den passenden *_API_KEY.
  • Zuerst eine einfache Nicht-Aktions-Frage testen („Was ist 2+2?“).
  • Server-Logs der Chat-Route prüfen.

KI lehnt Buchungen in Fremdwährung ab

  • Strenge FX-Regeln: Kurs + Quelle nötig.
  • Für neue Fremdbeträge braucht sie meist einen provisionalen Kurs (LLM_PROVISIONAL).
  • Sagt sie, sie findet keinen Kurs: mehr Kontext liefern oder web_search-fähiges Modell nutzen.
  • Kommt später ein Auszug: nur eine Anpassungsbuchung anfordern.

Alles wird zum Vorschlag, obwohl entsperrt

  • Chat-Sperre kann an sein (Schloss-Icon prüfen).
  • Oder die Aktion ist destruktiv / Stammdaten (immer Vorschläge).
  • Oder Validierung gescheitert (unausgeglichenes Journal, unbekannter Kontocode usw.).

Git-Modell / View-Verwirrung

„Ich sehe meine neuesten Buchungen nicht“ oder Zahlen wirken falsch

  • Du betrachtest wahrscheinlich einen Branch oder einen vergangenen asOf-Punkt.
  • Persistenten Books View Indicator oben prüfen.
  • Darauf klicken oder Git-Controls nutzen, um zu main (current) zurückzukehren.

Restore „hat nichts getan“ oder Arbeit scheint weg

  • Restore erzeugt immer einen neuen ROLLBACK-Commit auf dem Ziel-Branch.
  • Nach Restore wird die URL auf den neuen Head aktualisiert (kein asOf).
  • Deine alte Arbeit existiert weiter in der Historie – Commit-Liste oder Blame nutzen, um sie zu finden.

Chat oder Panels ignorieren meinen Branch

  • Alle wichtigen Panels lesen ?branch und ?asOf aus der URL.
  • Korrekte URL prüfen oder Branch-Selector in der History-Ansicht nutzen.
  • Der Chat erhält den aktuellen View immer von der App.

Backup & Restore

Restore scheitert mit Encryption-Key-Fehler

  • Das Backup wurde mit einem anderen ENCRYPTION_KEY erstellt.
  • Auf der Zielinstanz muss exakt derselbe Key für verschlüsselte Daten (Bank-Credentials usw.) gelten.
  • Siehe entrytwo_v1/docs/ENCRYPTION-KEY-ROTATION.md.

„.etbackup file is too large“ oder Import-Timeout

  • Große Backups können lange dauern.
  • Das System hat konfigurierbare Limits (BACKUP_MAX_* Env-Vars).
  • Bei sehr großen Instanzen als Fallback pg_dump + manuelles Kopieren der File-Assets erwägen (fortgeschritten).

Updates

„No update available“ oder Update deaktiviert

  • UPDATE_MANIFEST_URL nicht gesetzt, oder Manifest leer / unerreichbar.
  • Signaturprüfung scheitert (Cosign-Einstellungen und Logs prüfen).
  • Lizenzierte Instanz nach Trial ohne aktive Wartung (erwartetes Verhalten).

Update angewendet, dann Rollback

  • Healthcheck nach Migration fehlgeschlagen.
  • Update-Logs und das automatisch erzeugte Pre-Update-Backup prüfen.
  • Bei Bedarf Backup manuell restoren.

Lizenzierung / Trial

Trial-Paywall erscheint zu früh oder zu spät

  • Die 30-Tage-Uhr startet bei erster Nutzung in der Instanz (firstUseAt in Settings), nicht zur Download-Zeit.
  • Zum Debuggen bei direktem DB-Zugriff license.firstUseAt prüfen.

Lizenzschlüssel „invalid“ nach Kauf

  • Vollständigen et1....-Key einfügen.
  • Der Key wird einmal bei der Aktivierung geprüft; danach gilt nur das gespeicherte Flag („einmal verifizieren, für immer vertrauen“).
  • Bei wiederholtem Aktivierungsfehler Support mit Key und Instanzdetails kontaktieren.

Performance / Allgemein

Langsames Ledger oder Berichte

  • Große Historie ohne passende Indizes oder ohne Read-Replica.
  • Zeiträume eingrenzen oder asOf-View für historische Reports nutzen.
  • Bei schwerer Report-Last Read-Replicas erwägen.

Anhänge fehlen oder 404

  • Uploads-Volume in Docker korrekt gemountet?
  • Dateirechte im Container prüfen.

Wo du mehr Hilfe bekommst

  1. In-App-Chat mit aktuellem View fragen – er hat Live-Kontext + diese Docs.
  2. Dieses Dokumentationsset in ein anderes Modell laden und exakte Symptome + Books View Indicator beschreiben.
  3. Server-Logs prüfen (docker compose logs app oder dein Process-Manager).
  4. Bei Self-Hosted-Update- oder Lizenzproblemen exakte Version und Manifest-Status aus Admin → Update mitgeben.

Beim Melden von Issues angeben:

  • Was du tun wolltest
  • Aktueller View (Branch + asOf oder „on main current“)
  • Fehlermeldungen (exakter Text)
  • Ob Chat-Sperre an oder aus war
  • Letzte Aktionen (Upload, Abstimmen, Restore usw.)

Das macht es für Mensch oder KI deutlich schneller, zu helfen.