Troubleshooting¶

Step 1 — Check the logs:

docker compose logs backend --tail=50

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

Common error messages and solutions:

The most common cause is a data volume from an older ArangoDB version. Check:

docker compose logs arangodb --tail=30

If "Invalid version" or "upgrade required" appears:

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

Check worker status:

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

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

Common cause: REDIS_URL not set or Redis not reachable. Test the Redis connection:

docker compose exec valkey valkey-cli ping
# Expected response: PONG

Kamerplanter automatically creates all collections on startup. If collections are missing, the startup hook was not executed. Restart the backend:

docker compose restart backend

kubectl rollout restart deployment/kamerplanter-backend

Alternatively, check the ArangoDB web UI (default: http://localhost:8529) to verify that the kamerplanter database and kamerplanter_graph exist.

Kamerplanter runs seed migrations at startup (seed_data, seed_starter_kits, seed_location_types). On failure, check the backend logs for the full stack trace.

Common cause: ArangoDB starts slower than the backend. Increase the healthcheck interval or use depends_on with condition: service_healthy. Restart the backend after ArangoDB is fully started.

The named graph kamerplanter_graph is created on first startup. If it is missing, ensure_collections() initialization was skipped. Restart the backend or create the graph manually in the ArangoDB web UI under "Graphs".

Check:

1. Correct email and password? Demo account: demo@kamerplanter.local / demo-passwort-2024
2. Email verification required? If REQUIRE_EMAIL_VERIFICATION=true is set, the email must be confirmed. Set to false for development.
3. JWT secret key changed? All active tokens become invalid. Users must log in again.

The email address already exists in the system. Use the password reset flow, or check the email in the ArangoDB web UI under the users collection.

JWT access tokens expire after 15 minutes (default). The frontend client automatically renews the token using the refresh token (valid 30 days). If refresh token renewal fails:

• Check JWT_SECRET_KEY in the environment — if this value was changed, all refresh tokens become invalid.
• Check browser cookies — the HttpOnly cookie refresh_token must be set.

CORS errors appear in the browser console as:

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

Solution: Add the frontend origin to CORS_ORIGINS:

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

Format: JSON array as a string. Separate multiple entries with commas.

Check the Origin header actually being sent:

1. Browser DevTools → Network → Request Headers → Origin
2. Add this exact value (including http:// vs. https:// and port) to CORS_ORIGINS.
3. Restart the backend after the configuration change.

An active IPM treatment has an open pre-harvest interval (PHI). The harvest is blocked until the PHI has passed.

Steps:

1. Navigate to Pest Management > Treatment Applications.
2. Check active treatments with status "active" or "pre-harvest interval".
3. The system shows the earliest possible harvest date.

Check whether harvest indicators are configured for the plant species. Navigate to Master Data > [Species] > Harvest Indicators and add at least one indicator.

Check:

1. Feed token valid? Under Calendar > iCal Feeds, verify the feed is active.
2. Calendar app: URL must follow the format https://[host]/api/v1/calendar/ical/[token].
3. Time zone: iCal feeds use UTC. Check whether your calendar application interprets time zones correctly.

Navigate to Calendar and check:

• Are there planting runs or tasks in the selected period?
• Are the filters (phase, category) set too narrowly?
• Any backend API errors in browser DevTools (F12 → Network → /api/v1/...)?

Check whether starter kit seed data was loaded:

docker compose logs backend | grep -i "seed_starter_kits"

If "0 starter kits loaded" appears, trigger the seed migration manually:

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

The personal tenant is automatically created at registration. If it is missing:

1. GET /api/v1/t/ — check whether the tenant endpoint returns data.
2. If empty: run through the onboarding again or create a tenant manually under Settings > Tenants.

Common causes:

The backend container is not running or is failing its health check:

docker compose ps
# Status "unhealthy" or "Exit X" → restart container

docker compose up -d backend

Test the health check endpoint directly:

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

In Light Mode (KAMERPLANTER_MODE=light), token authentication is disabled for most endpoints. Check:

1. Is KAMERPLANTER_MODE=light set in the backend environment?
2. Was the backend restarted after the change?
3. Is the request actually reaching the backend port (8000) and not a proxy?

docker compose exec backend env | grep KAMERPLANTER_MODE
# Expected output: KAMERPLANTER_MODE=light

New collections or edge definitions are handled by ensure_collections() on startup. If collections are missing or newly added:

1. Check backend logs for startup errors.
2. Make sure the backend container was fully restarted during the update.
3. Verify ArangoDB collections manually via the web UI.

In Kubernetes deployments, the frontend build is served as static files by the backend. Check:

kubectl describe pod kamerplanter-backend-[hash]
# Check volume mounts for /app/static

Alternatively: deploy the frontend as a separate Nginx container.