Troubleshooting
Common issues and solutions
Docker Issues
Container fails to start
Check logs:
docker compose logs api
docker compose logs workerCommon causes:
- Database not ready: Wait for healthcheck or restart
- Missing environment variables: Check
.envfile
Build fails
Clear Docker cache:
docker compose down -v
docker system prune -a
docker compose build --no-cache
docker compose up -dPort conflicts
Check if ports are in use:
netstat -tulpn | grep :9000
netstat -tulpn | grep :9100Update ports in docker-compose.yml if needed.
Database Issues
Migration errors
Reset migrations:
docker compose exec api python manage.py migrate --fake-initialpgvector not installed
Install the extension:
docker compose exec api python manage.py install_pgvectorOr manually in PostgreSQL:
CREATE EXTENSION vector;Authentication Issues
Invalid credentials
Check if user exists:
docker compose exec api python manage.py shell -c "from users.models import Users; print(Users.objects.filter(username='admin').exists())"Reset password:
docker compose exec api python manage.py shell -c "from users.models import Users; u = Users.objects.get(username='admin'); u.set_password('newpassword'); u.save()"JWT token expired
Tokens expire after 24 hours. Use the refresh endpoint:
POST /api/v1/auth/refresh/CORS Errors
Ensure frontend URL matches backend CORS settings. Check:
VITE_API_URLin frontend.env- CORS settings in Django settings
Email Issues
Emails not sending
Check SMTP configuration:
EMAIL_HOST=smtp.provider.com
EMAIL_PORT=587
EMAIL_USE_TLS=True
EMAIL_HOST_USER=[email protected]
EMAIL_HOST_PASSWORD=passwordTest email sending:
docker compose exec api python manage.py shell
>>> from util.Mailer import send_email
>>> send_email("[email protected]", "Test", "Test message")Celery worker not processing tasks
Check worker status:
docker compose logs workerRestart worker:
docker compose restart workerWebSocket Issues
Notifications not working
Check Daphne is running on the correct port. Verify WebSocket URL:
VITE_WS_NOTIFICATIONS_URL=wss://yourdomain.com/ws/notifications/For local development:
VITE_WS_NOTIFICATIONS_URL=ws://localhost:9100/ws/notifications/