hoerdle/TROUBLESHOOTING.md

# Troubleshooting Guide

## Application Error: "a server-side exception has occurred"

Dieser Fehler tritt auf, wenn die Next.js-Anwendung auf dem Server einen Fehler hat.

### ⚠️ Datenbank-Berechtigungen (wenn DB von anderem Server kopiert wurde)

**Symptom**: Application Error nach dem Kopieren einer Datenbank von einem anderen Server

**Ursache**: SQLite benötigt Schreibrechte auf:
- Die Datenbankdatei selbst (`prod.db`)
- Das Datenbankverzeichnis (für temporäre Dateien wie `-wal`, `-shm`)

**Sofort-Lösung (auf dem Server ausführen)**:
```bash
# 1. Setze Berechtigungen für Datenbankverzeichnis und Datei
chmod 775 ./data
chmod 664 ./data/prod.db

# 2. Falls temporäre SQLite-Dateien existieren, auch diese:
chmod 664 ./data/*.db-wal 2>/dev/null || true
chmod 664 ./data/*.db-shm 2>/dev/null || true

# 3. Oder verwende das Fix-Skript:
./scripts/fix-database-permissions.sh

# 4. Container neu starten
docker compose restart hoerdle

# 5. Logs prüfen
docker logs hoerdle --tail=50
```

**Warum passiert das?**
- Wenn du eine Datenbankdatei von einem anderen Server kopierst, behält sie die ursprünglichen Berechtigungen
- SQLite muss Schreibrechte haben, um zu funktionieren
- Auch das Verzeichnis braucht Schreibrechte (für SQLite-WAL-Modus) 

### Sofort-Diagnose (auf dem Server ausführen)

```bash
# 1. Container-Logs prüfen (die wichtigste Information!)
docker logs hoerdle --tail=100

# 2. Container-Status prüfen
docker ps | grep hoerdle

# 3. Prüfe ob Datenbank existiert
docker exec hoerdle ls -lh /app/data/prod.db

# 4. Prüfe ob Server auf Port 3000 antwortet (intern)
docker exec hoerdle curl -f http://localhost:3000/api/daily

# 5. Prüfe Health Check
docker inspect hoerdle --format='{{json .State.Health}}' | python3 -m json.tool
```

### Häufige Ursachen und Lösungen

#### 1. Datenbankfehler / Migrationen fehlgeschlagen

**Symptom**: Logs zeigen Prisma-Fehler oder "database locked"

**Lösung**:
```bash
# Container-Logs prüfen
docker logs hoerdle | grep -i "migration\|database\|prisma"

# Falls Migrationen fehlgeschlagen sind:
docker compose restart hoerdle

# Bei persistierenden Problemen: Datenbank-Backup prüfen
ls -lh ./backups/
```

#### 2. Container läuft nicht oder ist crashed

**Symptom**: Container existiert nicht oder Status zeigt "Exited"

**Lösung**:
```bash
# Container-Status prüfen
docker ps -a | grep hoerdle

# Container neu starten
docker compose up -d

# Falls Container nicht startet, Logs prüfen
docker logs hoerdle --tail=200
```

#### 3. Caddy kann Container nicht erreichen

**Symptom**: 502 Bad Gateway oder "connection refused" in Caddy-Logs

**Lösung**:
```bash
# Prüfe ob hoerdle Container läuft
docker ps | grep hoerdle

# Prüfe Netzwerk
docker network inspect hoerdle_default

# Prüfe Caddy-Logs
docker logs hoerdle-caddy --tail=50

# Stelle sicher, dass Caddyfile Port 3000 verwendet (nicht 3010!)
grep "reverse_proxy" Caddyfile
```

#### 4. Fehlende Umgebungsvariablen

**Symptom**: Logs zeigen undefined variables

**Lösung**:
```bash
# Prüfe wichtige Umgebungsvariablen
docker exec hoerdle env | grep -E "DATABASE_URL|NODE_ENV"

# Prüfe .env Datei (falls vorhanden)
cat .env | grep DATABASE_URL
```

#### 5. Build-Fehler oder fehlerhafte Dateien

**Symptom**: Container startet, aber App crasht sofort

**Lösung**:
```bash
# Container komplett neu bauen
docker compose down
docker compose build --no-cache
docker compose up -d

# Prüfe Build-Logs
docker compose build 2>&1 | tee build.log
```

### Detaillierte Log-Analyse

```bash
# Alle Fehler in Logs finden
docker logs hoerdle 2>&1 | grep -i -E "error|exception|fatal|panic" | tail -50

# Prisma-spezifische Fehler
docker logs hoerdle 2>&1 | grep -i prisma | tail -20

# Next.js-spezifische Fehler
docker logs hoerdle 2>&1 | grep -i "next\|react" | tail -20
```

### Netzwerk-Debugging

```bash
# Teste Verbindung von Caddy zu Hördle
docker exec hoerdle-caddy wget -O- http://hoerdle:3000/api/daily

# Prüfe alle Container im Netzwerk
docker network inspect hoerdle_default --format='{{range .Containers}}{{.Name}}: {{.IPv4Address}}{{"\n"}}{{end}}'
```

### Datenbank-Debugging

```bash
# Prüfe Datenbank-Integrität
docker exec hoerdle npx prisma db pull

# Prüfe Datenbank-Struktur
docker exec hoerdle npx prisma studio &
# (dann Browser öffnen - erfordert X11 forwarding oder lokalen Zugriff)
```

### Quick-Fix: Vollständiger Neustart

Wenn nichts anderes hilft:

```bash
# 1. Backup erstellen
cp ./data/prod.db ./backups/prod_$(date +%Y%m%d_%H%M%S).db

# 2. Container stoppen
docker compose down

# 3. Container neu starten
docker compose up -d

# 4. Logs beobachten
docker compose logs -f
```

## Bei weiterem Bedarf

Sammle folgende Informationen für weitere Hilfe:

```bash
echo "=== Container Status ===" && \
docker ps -a | grep hoerdle && \
echo -e "\n=== Letzte 50 Log-Zeilen ===" && \
docker logs hoerdle --tail=50 && \
echo -e "\n=== Fehler in Logs ===" && \
docker logs hoerdle 2>&1 | grep -i error | tail -20
```

Kopiere die vollständige Ausgabe und sende sie weiter.