Debugging¶

This page explains how to debug the backend and frontend in the local development environment. All methods assume a running Skaffold setup (see Local Setup).

Backend Debugging with debugpy¶

The backend container image includes debugpy — the Python debugger used by VS Code, PyCharm, and other IDEs for remote debugging.

Starting debug mode¶

skaffold debug --port-forward

The debug profile in skaffold.yaml sets DEBUGPY_ENABLED=true as a Docker build argument. The container then starts debugpy and optionally waits for a connection.

Debugpy listens on port 5678. Skaffold does not forward this port automatically — it must be set up manually:

kubectl port-forward deployment/kamerplanter-backend 5678:5678

VS Code — launch.json¶

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Kamerplanter Backend (Remote)",
      "type": "debugpy",
      "request": "attach",
      "connect": {
        "host": "localhost",
        "port": 5678
      },
      "pathMappings": [
        {
          "localRoot": "${workspaceFolder}/src/backend",
          "remoteRoot": "/app"
        }
      ],
      "justMyCode": true
    }
  ]
}

PyCharm — Remote debug configuration¶

1. Menu: Run → Edit Configurations → + → Python Debug Server
2. Host: localhost, Port: 5678
3. Path Mappings: src/backend/app → /app/app
4. Start the configuration, then run skaffold debug --port-forward

Breakpoints and log output¶

The backend server runs with uvicorn in --reload mode. Structured logs are output via structlog:

import structlog

log = structlog.get_logger()

async def create_species(data: CreateSpeciesRequest) -> Species:
    log.info("creating_species", scientific_name=data.scientific_name)
    # Set a breakpoint here
    result = await self.repo.create(data)
    log.info("species_created", key=result.key)
    return result

Viewing pod logs¶

Without a debugger, logs often provide enough information:

# Backend logs (last 100 lines, then follow live)
kubectl logs -l app=kamerplanter-backend --tail=100 -f

# Celery worker logs
kubectl logs -l app=kamerplanter-worker --tail=100 -f

# Errors only
kubectl logs -l app=kamerplanter-backend --tail=200 | grep '"level":"error"'

Frontend Debugging¶

Browser DevTools¶

Most frontend issues can be resolved with browser developer tools:

• Console (F12 → Console): JavaScript errors, unhandled promise rejections, i18n warnings for missing keys
• Network (F12 → Network): API requests, HTTP status codes, request/response bodies
• Redux DevTools: Track Redux state changes (browser extension for Chrome/Firefox required)

React Developer Tools¶

The React DevTools browser extension allows you to: - Inspect the component tree - View props and state of individual components - Use the re-render profiler for performance analysis

Vite Source Maps¶

In development mode (Vite dev server, port 5173), source maps are active. Breakpoints can be set directly in TypeScript files in the browser debugger.

Common Frontend Issues¶

ArangoDB Web UI¶

The ArangoDB web interface is available at http://localhost:8529:

Useful AQL queries for debugging:

// Show all plant species
FOR s IN species RETURN s

// Check connections for a tenant
FOR v, e IN 1..1 OUTBOUND 'tenants/demo' GRAPH 'kamerplanter_graph'
  RETURN { vertex: v._id, edge: e._from }

// Last 10 tasks
FOR t IN tasks
  SORT t.created_at DESC
  LIMIT 10
  RETURN t

Debugging Celery Tasks¶

Background tasks (Celery Beat + Worker) have separate logs:

# Celery worker
kubectl logs -l app=kamerplanter-worker -f

# Celery Beat (scheduler)
kubectl logs -l app=kamerplanter-beat -f

Trigger a task manually (direct Python call in the backend pod):

kubectl exec -it deployment/kamerplanter-backend -- python -c "
from app.tasks.care_reminders import generate_due_care_reminders
result = generate_due_care_reminders.delay()
print('Task ID:', result.id)
"

Health Endpoints¶

The backend provides two health endpoints that are also useful for manual diagnostics:

# Liveness (is the process running?)
curl http://localhost:8000/api/v1/health/live

# Readiness (is the database reachable?)
curl http://localhost:8000/api/v1/health/ready

Expected response (both): {"status": "ok"} with HTTP 200.

Common Error Scenarios¶

kubectl logs <backend-pod-name> -c init-seed

See also¶

• Local Setup
• Testing
• Code Standards