Troubleshooting¶

Diagnostic checklist¶

Before investigating specific symptoms, collect basic information:

# Are all containers running?
docker compose ps

# Recent logs per service
docker compose logs --tail=50 backend
docker compose logs --tail=50 frontend
docker compose logs --tail=50 livekit
docker compose logs --tail=50 keycloak

Application issues¶

App returns 404 on all routes¶

Cause: DJANGO_SETTINGS_MODULE is not set in .env.

Fix: Add DJANGO_SETTINGS_MODULE=meet.settings to .env and restart.

502 Bad Gateway on all routes¶

Cause: The frontend container nginx is not listening on port 8083, or the backend is unreachable.

Steps: 1. Check docker logs meet-frontend-1 for nginx errors 2. If you see /etc/nginx/conf.d is not writable — the template mechanism failed. Fix: mount nginx-routing.conf directly to /etc/nginx/conf.d/routing.conf (not to the templates directory) 3. Verify the backend is running: docker compose ps backend

API returns 301 in a loop / site keeps loading¶

Cause: Django's SECURE_SSL_REDIRECT is active and the nginx routing config is forwarding HTTP instead of HTTPS to the backend.

Fix: In nginx-routing.conf, the backend proxy location must hardcode the proto header:

proxy_set_header X-Forwarded-Proto https;  # NOT $scheme

Login redirects but loops back to login page¶

Cause A: OIDC redirect URI mismatch.

Meet's callback URL is https://visio.example.com/api/v1.0/callback/ — not the standard /oidc/callback/. Update your OIDC provider's client configuration to use the correct URI (including the trailing slash).

Cause B: Backend cannot reach Keycloak for token exchange.

The backend container needs extra_hosts to resolve the Keycloak hostname:

backend:
  extra_hosts:
    - "auth.example.com:host-gateway"

Cause C: Session cookie mismatch — DJANGO_CSRF_TRUSTED_ORIGINS does not include your full HTTPS domain.

"Invalid parameter: redirect_uri" from Keycloak¶

The redirect URI sent by Meet does not match what's registered in Keycloak. Update it via the Keycloak admin API:

KC_IP=$(docker inspect meet-keycloak-1 --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' | tr ' ' '\n' | tail -1)

TOKEN=$(curl -s -X POST "http://$KC_IP:8080/realms/master/protocol/openid-connect/token" \
  -d "client_id=admin-cli&username=admin&password=<KC_ADMIN_PASSWORD>&grant_type=password" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

UUID=$(curl -s "http://$KC_IP:8080/admin/realms/meet/clients?clientId=meet" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)[0]['id'])")

curl -s -X PUT "http://$KC_IP:8080/admin/realms/meet/clients/$UUID" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"redirectUris":["https://visio.example.com/api/v1.0/callback/"],"webOrigins":["https://visio.example.com"]}'

Database migration errors¶

# Check migration status
docker exec -u root meet-backend-1 python manage.py showmigrations

# Run pending migrations
docker exec -u root meet-backend-1 python manage.py migrate

Audio/Video issues¶

Disconnected from meeting immediately / "You left the meeting"¶

Most likely cause: LiveKit WebSocket is unreachable from the browser.

The browser connects to the URL returned by GET /api/v1.0/rooms/{id}/token/. If LIVEKIT_API_URL is set to the Docker-internal address (http://livekit:7880), browsers receive that address and can't connect.

Fix: LIVEKIT_API_URL must be the public HTTPS URL:

LIVEKIT_API_URL=https://livekit.example.com

Verify the LiveKit subdomain is accessible:

curl -s -o /dev/null -w "%{http_code}" https://livekit.example.com/
# Expected: 200

Can join the room but no audio/video¶

Cause: UDP port 7882 is blocked.

LiveKit falls back to TCP (port 7881) when UDP is unavailable, which increases latency significantly. Verify: 1. Port 7882/UDP is open in your cloud provider's firewall (security group / network rules) 2. Port 7881/TCP is also open for TCP fallback

Audio works but video is very pixelated or choppy¶

Cause: Network congestion or insufficient server bandwidth.

LiveKit's simulcast should adapt automatically. If it doesn't: 1. Check server bandwidth — LiveKit forwards all streams through the server 2. Have participants check their own connection speed 3. Review LiveKit metrics (see Monitoring)

Recording issues¶

Recording button is missing¶

Recording requires LiveKit Egress and S3 storage to be configured. Ensure the following env vars are set: - AWS_S3_ENDPOINT_URL - AWS_S3_ACCESS_KEY_ID - AWS_S3_SECRET_ACCESS_KEY - AWS_STORAGE_BUCKET_NAME

Recording starts but file never appears¶

1. Check Egress logs: docker compose logs livekit-egress
2. Check Garage: docker compose exec garage garage object list meet-media-storage/recordings/
3. Check webhook delivery: docker compose logs backend | grep storage-hook
4. Verify STORAGE_WEBHOOK_AUTH_TOKEN matches the Garage webhook config

Docker and container issues¶

docker compose exec fails with "invalid USER value"¶

Docker user namespace remapping is active on this system. Use docker exec -u root instead:

# Instead of:
docker compose exec backend python manage.py migrate

# Use:
docker exec -u root meet-backend-1 python manage.py migrate

Container keeps restarting¶

docker compose logs --tail=30 <service>

Common causes: - Missing required environment variable (check for ImproperlyConfigured errors) - Port already in use on the host - Permission error on a mounted volume

Out of disk space¶

df -h

# Clean unused Docker resources
docker system prune -f
docker volume prune -f  # WARNING: removes unused volumes

Getting more help¶

1. Search existing issues: github.com/suitenumerique/meet/issues
2. Matrix community: #meet-official:matrix.org
3. Open a new issue — include your Meet version, deployment method, and relevant logs