hoerdle/docs/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):

# 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)

# 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:

# 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:

# 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:

# 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:

# 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:

# 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

# 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

# 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

# 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:

# 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:

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.