---
title: Troubleshooting
linkTitle: Troubleshooting
weight: 8
toc: true
---

Typische Probleme und Lösungen. Wenn dein Problem nicht dabei ist → [Issue auf Gitea](https://git.kgva.ch/karim/RAPPORT/issues).

## App startet nicht

### "Rapport ist beschädigt" beim ersten Start

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

**Lösung:** siehe [Installation § 3](../installation#3--erster-start-macos-gatekeeper). Kurz:

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

### App startet, zeigt aber schwarzen Bildschirm

**Ursache:** WebView-Cache korrupt.

**Lösung:**

```bash
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:**

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

**Lösung:**

1. Backup wiederherstellen (siehe [Datenhaltung](../datenhaltung#wiederherstellung))
2. **Oder** als letzter Ausweg: Daten zurücksetzen
   ```bash
   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**:
   ```bash
   cp -R "~/Library/Application Support/com.rapport.app" \
         "~/Documents/Rapport-Notfall-$(date +%Y%m%d-%H%M)"
   ```
3. [Issue erstellen](https://git.kgva.ch/karim/RAPPORT/issues/new) 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](../web-modus) wechseln (Postgres ohne praktisches Limit)

## Updates

### Auto-Update findet nichts

**Diagnose:**

```bash
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](https://git.kgva.ch/karim/RAPPORT/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`](https://github.com/schoero/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:**

```bash
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](../web-modus#troubleshooting).

## Debug-Informationen sammeln

Bei einem Issue helfen folgende Infos:

```bash
# 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](https://git.kgva.ch/karim/RAPPORT/issues/new) 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