Betriebs-Fehlerbehebung¶

Schritt 1 — Logs prüfen:

docker compose logs backend --tail=50

kubectl logs deployment/kamerplanter-backend --tail=50

Typische Fehlermeldungen und Lösungen:

Häufigste Ursache ist ein Datenvolume aus einer alten ArangoDB-Version. Prüfe:

docker compose logs arangodb --tail=30

Wenn "Invalid version" oder "upgrade required" erscheint:

docker compose down
docker volume rm kamerplanter_arangodb_data
docker compose up -d

Prüfe den Worker-Status:

docker compose logs celery-worker --tail=30
docker compose logs celery-beat --tail=30

kubectl logs deployment/kamerplanter-celery-worker --tail=30

Häufige Ursache: REDIS_URL nicht gesetzt oder Redis nicht erreichbar. Redis-Verbindung testen:

docker compose exec valkey valkey-cli ping
# Erwartete Antwort: PONG

Kamerplanter legt beim Start automatisch alle Collections an. Wenn Collections fehlen, wurde der Startup-Hook nicht ausgeführt. Backend neu starten:

docker compose restart backend

kubectl rollout restart deployment/kamerplanter-backend

Alternativ in der ArangoDB-Web-UI (Standard: http://localhost:8529) prüfen, ob die Datenbank kamerplanter und der Graph kamerplanter_graph existieren.

Kamerplanter führt Seed-Migrationen beim Startup aus (seed_data, seed_starter_kits, seed_location_types). Bei Fehler im Log:

1. Vollständigen Stack-Trace aus den Backend-Logs entnehmen.
2. Häufige Ursache: ArangoDB startet langsamer als das Backend — Healthcheck-Intervall erhöhen oder depends_on mit condition: service_healthy nutzen.
3. Backend erneut starten nach vollständig gestartetem ArangoDB.

Der Named Graph kamerplanter_graph wird beim ersten Start erstellt. Wenn er fehlt, wurde die ensure_collections()-Initialisierung übersprungen. Backend neu starten oder manuell in der ArangoDB-Web-UI unter "Graphs" den Graph anlegen.

Prüfe:

1. Korrekte E-Mail und Passwort? Demo-Account: demo@kamerplanter.local / demo-passwort-2024
2. E-Mail-Verifikation erforderlich? Wenn REQUIRE_EMAIL_VERIFICATION=true gesetzt ist, muss die E-Mail bestätigt sein. In der Entwicklungsumgebung auf false setzen.
3. JWT-Schlüssel geändert? Alle aktiven Tokens verlieren ihre Gültigkeit. Neu anmelden.

Die E-Mail-Adresse existiert bereits im System. Passwort-zurücksetzen verwenden oder die E-Mail in der ArangoDB-Web-UI unter users-Collection prüfen.

JWT-Access-Token läuft nach 15 Minuten ab (Standard). Der Frontend-Client erneuert den Token automatisch per Refresh-Token (gültig 30 Tage). Wenn Refresh-Token-Erneuerung fehlschlägt:

• JWT_SECRET_KEY in der Umgebung prüfen — wenn dieser Wert geändert wurde, werden alle Refresh-Tokens ungültig.
• Browser-Cookies prüfen — HttpOnly-Cookie refresh_token muss gesetzt sein.

CORS-Fehler (Zugriffssperre durch Browser-Sicherheitsrichtlinie) erscheinen in der Browser-Konsole als:

Access to XMLHttpRequest at 'http://localhost:8000/api/...' has been blocked by CORS policy

Lösung: Den Origin des Frontend in CORS_ORIGINS eintragen:

# .env
CORS_ORIGINS=["http://localhost:5173","http://localhost:3000"]

Format: JSON-Array als String. Mehrere Einträge durch Komma trennen.

Prüfe den tatsächlich gesendeten Origin-Header:

1. Browser DevTools → Network → Request-Header → Origin
2. Diesen Wert exakt (inkl. http:// vs. https:// und Port) in CORS_ORIGINS eintragen.
3. Backend neu starten nach Konfigurationsänderung.

Eine aktive IPM-Behandlung hat eine offene Karenzzeit (Pre-Harvest Interval). Die Ernte ist bis zum Ende der Karenzzeit gesperrt.

Vorgehen:

1. Navigiere zu Pflanzenschutz > Behandlungsanwendungen.
2. Prüfe aktive Behandlungen mit dem Status "aktiv" oder "karenzzeit".
3. Das System zeigt das früheste mögliche Erntedatum an.

Prüfe, ob alle Ernteindikatoren für die Pflanzenart konfiguriert sind. Navigiere zu Stammdaten > [Art] > Ernteindikatoren und trage mindestens einen Indikator ein.

Prüfe:

1. Feed-Token gültig? Unter Kalender > iCal-Feeds prüfen ob der Feed aktiv ist.
2. Kalender-App: URL muss das Format https://[host]/api/v1/calendar/ical/[token] haben.
3. Zeitzone: iCal-Feeds verwenden UTC. Prüfe ob deine Kalenderanwendung Zeitzonen korrekt interpretiert.

Navigiere zu Kalender und prüfe:

• Sind Pflanzdurchläufe oder Aufgaben im gewählten Zeitraum vorhanden?
• Sind die Filter (Phase, Kategorie) zu eng gesetzt?
• Backend-API-Fehler in den Browser DevTools (F12 → Network → /api/v1/...)?

Prüfe ob Starter-Kit-Seeddaten geladen wurden:

docker compose logs backend | grep -i "seed_starter_kits"

Wenn "0 starter kits loaded" erscheint, Seed-Migration manuell auslösen:

docker compose exec backend python -c "from app.migrations.seed_starter_kits import run_seed_starter_kits; run_seed_starter_kits()"

Der persönliche Mandant wird automatisch bei der Registrierung erstellt. Falls er fehlt:

1. GET /api/v1/t/ — prüfen ob der Tenant-Endpoint Daten zurückliefert.
2. Falls leer: Onboarding erneut durchlaufen oder Mandant manuell unter Einstellungen > Mandanten anlegen.

Häufige Ursachen:

Der Backend-Container läuft nicht oder besteht den Healthcheck nicht:

docker compose ps
# Status "unhealthy" oder "Exit X" → Container neu starten

docker compose up -d backend

Healthcheck-Endpunkt direkt prüfen:

curl http://localhost:8000/api/v1/health/live
# Erwartete Antwort: {"status": "ok"}

CrashLoopBackOff (Kubernetes-Fehler: Container startet wiederholt und schlägt fehl) bedeutet, dass der Container kurz nach dem Start abstürzt. Logs des letzten Absturzes abrufen:

kubectl logs deployment/kamerplanter-backend --previous

Häufige Ursachen: fehlende Umgebungsvariablen, Datenbankverbindung nicht erreichbar oder fehlerhafte Konfigurationsdatei. Die Fehlermeldung im Log gibt in der Regel den genauen Grund an.

Im Light-Modus (KAMERPLANTER_MODE=light) entfällt die Token-Authentifizierung für die meisten Endpunkte. Prüfe:

1. KAMERPLANTER_MODE=light in der Backend-Umgebung gesetzt?
2. Backend nach der Änderung neu gestartet?
3. Anfrage geht tatsächlich an den Backend-Port (8000) und nicht an einen Proxy?

docker compose exec backend env | grep KAMERPLANTER_MODE
# Erwartete Ausgabe: KAMERPLANTER_MODE=light

Bei neuen Collections oder Kanten-Definitionen aktualisiert ensure_collections() den Graphen. Falls alte Collections fehlen oder neue hinzugekommen sind:

1. Backend-Logs auf Startup-Fehler prüfen.
2. Sicherstellen, dass der Backend-Container beim Update vollständig neugestartet wurde.
3. ArangoDB-Collections manuell über die Web-UI prüfen.

Bei Kubernetes-Deployments wird der Frontend-Build als Static Files durch das Backend ausgeliefert. Prüfe:

kubectl describe pod kamerplanter-backend-[hash]
# Volume-Mounts auf /app/static prüfen

Alternativ: Frontend separat als Nginx-Container deployen.