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üfen Sie:

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üfen Sie 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üfen Sie:

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 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üfen Sie 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. Navigieren Sie zu Pflanzenschutz > Behandlungsanwendungen.
2. Prüfen Sie aktive Behandlungen mit dem Status "aktiv" oder "karenzzeit".
3. Das System zeigt das früheste mögliche Erntedatum an.

Prüfen Sie, ob alle Ernteindikatoren für die Pflanzenart konfiguriert sind. Navigieren Sie zu Stammdaten > [Art] > Ernteindikatoren und tragen Sie mindestens einen Indikator ein.

Prüfen Sie:

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üfen Sie ob Ihre Kalenderanwendung Zeitzonen korrekt interpretiert.

Navigieren Sie zu Kalender und prüfen Sie:

• 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üfen Sie 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"}

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

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üfen Sie:

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

Alternativ: Frontend separat als Nginx-Container deployen.