RAPPORT-WEBSITE/content/docs/troubleshooting.md

title, linkTitle, weight, toc

title	linkTitle	weight	toc
Troubleshooting	Troubleshooting	8	true

Typische Probleme und Lösungen. Wenn dein Problem nicht dabei ist → Issue auf Gitea.

App startet nicht

"Rapport ist beschädigt" beim ersten Start

Ursache: macOS Gatekeeper blockt unsignierte/nicht-notarisierte Apps.

Lösung: siehe Installation § 3. Kurz:

xattr -d com.apple.quarantine /Applications/Rapport.app

App startet, zeigt aber schwarzen Bildschirm

Ursache: WebView-Cache korrupt.

Lösung:

rm -rf "~/Library/Caches/com.rapport.app"
rm -rf "~/Library/WebKit/com.rapport.app"

App neu starten. Daten gehen dabei nicht verloren (liegen in Application Support, nicht im Cache).

App stürzt sofort beim Start ab

Ursache: wahrscheinlich beschädigte JSON-Daten in studio_data_v1.

Diagnose:

# Daten ansehen (DevTools-Output)
open "~/Library/Application Support/com.rapport.app"

Lösung:

1. Backup wiederherstellen (siehe Datenhaltung)
2. Oder als letzter Ausweg: Daten zurücksetzen

   mv "~/Library/Application Support/com.rapport.app" \
      "~/Library/Application Support/com.rapport.app.bad"
   

   App neu starten → erstellt frische Daten. Anschliessend Setup-Screen.

Daten weg

Nach einem App-Update fehlen Einträge

Ursache: mögliche fehlgeschlagene Migration.

Sofortmassnahme:

1. Rapport beenden (Cmd+Q, nicht nur Fenster zu)
2. Aktuelles Datenverzeichnis sichern:

   cp -R "~/Library/Application Support/com.rapport.app" \
         "~/Documents/Rapport-Notfall-$(date +%Y%m%d-%H%M)"
   

3. Issue erstellen mit:
   • Version vor dem Update (falls bekannt)
   • Version nach dem Update
   • Was fehlt
   • Optional: gesicherter Datenordner (via Pastebin oder verschlüsselt zugesandt)

localStorage voll

Symptom: Rapport schreibt Fehler-Toast "Speicher voll" beim Sichern.

Ursache: macOS WebView limitiert localStorage auf ~10 MB pro Origin.

Lösung:

• Sehr grosse Logos durch kleinere ersetzen (Bürodaten → Logo)
• Belege (Spesen) selektiv löschen oder als externe Datei archivieren
• Auf Web-Modus wechseln (Postgres ohne praktisches Limit)

Updates

Auto-Update findet nichts

Diagnose:

curl -s https://git.kgva.ch/karim/RAPPORT/raw/branch/main/APP/latest.json

→ sollte JSON liefern. Wenn nicht: Server-/Netzwerkproblem.

Update lädt, lässt sich aber nicht installieren

Ursache: Signaturprüfung scheitert (Public-Key in App ≠ Signatur in latest.json).

Lösung: Manuelles Update — DMG direkt von Releases laden und installieren. Daten bleiben erhalten.

"Diese Version überspringen" rückgängig machen

In Einstellungen → Updates → Übersprungene Versionen zurücksetzen. Beim nächsten Start wird die Version wieder angeboten.

PDF / QR-Schein

QR-Schein hat falsche Daten

Diagnose-Checkliste:

• IBAN korrekt? (CH, 21 Zeichen, keine Leerzeichen)
• Empfänger-Adresse vollständig? (PLZ und Ort beide gefüllt)
• Schuldner-Adresse vollständig?
• Betrag > 0?
• Referenz nicht zu lang? (max 27 Zeichen)

QR-Bibliothek: swissqrbill — bei merkwürdigen Fehlern dort nachschauen.

PDF-Export ist leer / weisses Blatt

Ursache: Print-View hat keine Daten (möglicherweise Race-Condition beim Laden).

Lösung: Rechnung schliessen, erneut öffnen, dann PDF.

PDF-Schrift sieht falsch aus

Ursache: Web-Schrift nicht geladen, Fallback greift.

Lösung: Vor dem Drucken warten, bis das Vorschau-Bild komplett geladen ist (3–5 Sek).

System-Tray

Tray-Icon erscheint nicht

Plattform-Hinweis: Tray-Icons unter macOS sind bei extrem voller Menüleiste oder unter "Bartender"/"Hidden Bar" eventuell unsichtbar.

Diagnose:

ps aux | grep -i rapport

→ wenn Prozess läuft, aber kein Icon: in den Tray-Manager-Apps prüfen.

Konfiguration: Einstellungen → System-Tray → Tray-Icon ausblenden (aus → Icon erzwingen).

Tray-Menü reagiert nicht / hängt

Lösung: App via Activity Monitor hart beenden und neu starten. Daten gehen nicht verloren (alle Schreibungen sind synchron in localStorage).

Web-Modus

Login-Screen zeigt keine Server-URL

Ursache: .env.production enthielt nicht den richtigen VITE_SUPABASE_URL zur Build-Zeit.

Lösung: .env.production prüfen, dann npm run build neu, Container restart.

Realtime-Updates kommen nicht an

Ursache: Websocket-Support fehlt im Reverse Proxy.

Lösung: In Nginx Proxy Manager für api.* Websocket Support aktivieren.

Siehe Web-Modus § Troubleshooting.

Debug-Informationen sammeln

Bei einem Issue helfen folgende Infos:

# Rapport-Version
defaults read /Applications/Rapport.app/Contents/Info.plist CFBundleShortVersionString

# macOS-Version
sw_vers

# Architektur
uname -m

# Datenverzeichnis-Grösse
du -sh "~/Library/Application Support/com.rapport.app"

# Cache-Verzeichnis-Grösse
du -sh "~/Library/Caches/com.rapport.app"

→ Bei Issue mit anhängen.

Wenn nichts hilft

Neues Issue auf Gitea mit:

• Was du gemacht hast
• Was passiert ist
• Was du erwartet hättest
• Screenshots (auch von DevTools-Konsole falls möglich)
• Rapport-Version und macOS-Version