Troubleshooting

Troubleshooting & FAQ

Common issues, their causes, and how to fix them. Use the debug decision tree below to systematically diagnose problems.

Error Occurred? Check Logs First DB Issue? Check port 9433 Verify connection string, run setup_db.py Auth Issue? Check JWT secret Match JWT secret with SSO, check cookie Network Issue? Check ports & CORS Verify 8065 not in use, check Nginx config

Figure 1: Debug Decision Tree

Common Issues

Symptom Likely Cause Fix
Cannot start server on port 8065 Port already in use Kill the existing process or change port in .env
Health check returns "unhealthy" PostgreSQL not running Start PostgreSQL service, verify port 9433
Redirect to /login constantly Expired or missing JWT token Clear cookies and re-authenticate through SSO
401 Unauthorized on all API calls JWT secret mismatch Ensure jwt_secret_key matches ONETIMELOGIN SSO
Video does not play (black screen) Invalid stream URL or CORS Verify stream_url in video asset, check CDN CORS headers
Progress not saving Auth cookie missing or CSRF issue Check that access_token cookie is set, Bearer auth bypasses CSRF
Test submission returns 400 Max attempts reached Default is 3 attempts. Admin must increase max_attempts or reset.
Roku channel shows "Loading..." Cannot reach API server Verify apiBaseUrl in channel, check network/firewall
Roku pairing code does not work Code expired Restart the Roku channel to generate a new code
429 Too Many Requests Rate limit exceeded Wait 1 minute (default 100/min). Adjust rate_limit_default in config.

Port Conflicts (8065 in Use)

If port 8065 is already occupied, the server will fail to start with an "Address already in use" error.

# Find what is using port 8065 (Windows)
netstat -ano | findstr :8065

# Find what is using port 8065 (Linux)
sudo lsof -i :8065

# Kill the process by PID
taskkill /PID <pid> /F  (Windows)
kill -9 <pid>  (Linux)

Database Connection Issues

If the health check reports database connectivity problems, verify the following:

  • PostgreSQL service is running and listening on port 9433
  • Database rokuchannel exists (run python setup_db.py to create)
  • User postgres has access and the password matches DATABASE_URL in .env
  • The roku schema exists with all 11 tables
# Test connection manually
psql -h localhost -p 9433 -U postgres -d rokuchannel -c "SELECT count(*) FROM information_schema.tables WHERE table_schema='roku';"

Auth / JWT Errors

Authentication issues typically stem from token expiration or configuration mismatches.

  • 401 Unauthorized -- JWT is invalid or expired. Ensure jwt_secret_key matches between this app and ONETIMELOGIN SSO. Token TTL is 30 minutes by default.
  • 403 Forbidden -- User role is insufficient. Admin endpoints require role = ADMIN or SUPER_ADMIN in the JWT claims.
  • Login Redirect Loop -- The access_token cookie is missing or malformed. Clear all cookies, visit /login, and authenticate through SSO again.

Video Playback Issues

  • Black screen with play button -- The stream URL is likely unreachable. Check browser console for CORS or 404 errors. Verify the stream_url field in the video asset record.
  • Video buffers constantly -- HLS adaptive streaming should handle bandwidth changes. If buffering persists, check the CDN performance or use a lower quality stream URL (stream_url_sd).
  • HLS fatal error in console -- The .m3u8 manifest may be malformed or the segment URLs are invalid. Test the stream URL directly in an HLS validator tool.

Roku Device Pairing Failures

  • Code not accepted -- The pairing code has likely expired. Restart the Roku channel to get a fresh code and enter it within the time window.
  • Roku shows error after pairing -- The device cannot reach the API server. Ensure both the Roku and the server are on the same network, or that the production URL is accessible.
  • No content appears after pairing -- Verify you are enrolled in at least one channel. The Roku feed endpoint (/api/roku/feed/{channel_id}) requires a valid channel_id with published content.

Useful Debug Commands

# Health check with full details
curl -s http://localhost:8065/health | python -m json.tool

# API info (version, SSO URL, etc.)
curl -s http://localhost:8065/api/info | python -m json.tool

# Test database connectivity
psql -h localhost -p 9433 -U postgres -d rokuchannel -c "SELECT 1;"

# Check Redis connectivity
redis-cli -n 10 ping

# View application logs (production)
sudo journalctl -u rokuchannel -n 50 --no-pager