Skip to main content

🔧 Troubleshooting

This guide addresses the most common issues users encounter when deploying TriviaFlow.

🔴 WebSocket Connection Failed​

Symptoms:

  • The Lobby screen stays stuck on "Connecting..."
  • Players cannot join the game.
  • The browser console shows WebSocket connection to 'wss://...' failed.

Possible Causes & Solutions:

1. ALLOWED_HOSTS Mismatch​

The Django server rejects connections if the domain isn't explicitly allowed.

  • Check: Open .env and ensure ALLOWED_HOSTS matches your domain exactly.
  • Fix: ALLOWED_HOSTS=quiz.your-domain.com

2. Missing Caddy Headers​

If you are using a custom reverse proxy (Nginx/Apache) instead of the provided Caddyfile, you might be dropping the WebSocket Upgrade headers.

  • Fix: Ensure your proxy forwards Upgrade and Connection headers.
  • Caddy Example: The default Caddyfile handles this automatically.

3. Mixed Content (HTTP vs HTTPS)​

If your site is loaded over HTTPS, the WebSocket connection must use WSS (Secure WebSocket).

  • Check: If you are accessing via https://, the browser will block ws:// connections.
  • Fix: Ensure your CSRF_TRUSTED_ORIGINS includes https://.

🔒 CSRF Verification Failed​

Symptoms:

  • You cannot log in to the Admin Panel.
  • You see a "Forbidden (403)" error when submitting forms.

Solution: Django requires you to explicitly trust the domain you are serving the site from.

  • Fix: Open .env and add your full URL to CSRF_TRUSTED_ORIGINS. 
    CSRF_TRUSTED_ORIGINS=https://quiz.your-domain.com
  • Note: It must include the scheme (https://).

🐘 Database Connection Logic​

Symptoms:

  • The container restarts endlessly.
  • Logs show Access denied for user 'triviaflow'@'...'.

Solution: The database password in your .env file does not match what the database expects.

  • Fix:
    1. Stop containers: docker compose down
    2. Delete the volume: docker volume rm triviaflow_db_data (Warning: This deletes all data!)
    3. Restart: docker compose up -d Why? The database password is only set ONCE when the volume is first created. Changing .env afterwards does not update the running database password.

⏱️ Timer Not Syncing​

Symptoms:

  • The timer on the main screen and player phones don't match.
  • Questions skip automatically or get stuck.

Solution:

  • Check Redis: Ensure the redis container is running and healthy. docker compose logs redis.
  • Check Timezones: Ensure your server time is synced. TriviaFlow uses UTC internally.

📜 Viewing Logs​

If you are stuck, the most helpful thing is to read the application logs.

# View backend logs
docker compose logs -f web

# View database logs
docker compose logs -f db