How to troubleshoot common issues in Open edX?

Posted on by

Open edX is a complex platform with multiple components, including LMS, Studio, databases, and external integrations. Issues can arise from misconfigurations, software updates, or server failures. Below is a step-by-step troubleshooting guide for common Open edX problems.

1. General Troubleshooting Steps

  1. Check Logs for Errorssudo tail -f /edx/var/log/*/*.log
    • lms/edx.log → LMS-related issues
    • cms/edx.log → Studio-related issues
    • nginx/error.log → Web server issues
    • mysql/error.log → Database issues
  2. Restart Services sudo /edx/bin/supervisorctl restart all
  3. Clear Caches sudo /edx/bin/supervisorctl stop all sudo rm -rf /edx/var/cache/* sudo /edx/bin/supervisorctl start all
  4. Check Disk Spacedf -h
    • If storage is full, delete logs: sudo rm -rf /edx/var/log/*/*.log

2. LMS & Studio Not Loading

Possible Causes

✅ Nginx misconfiguration
✅ Database connectivity issues
✅ Missing environment variables

Fixes

  1. Check Nginx Configuration sudo nginx -t If errors appear, fix /etc/nginx/sites-enabled/lms and restart: sudo systemctl restart nginx
  2. Check MySQL/MongoDB sudo systemctl status mysql sudo systemctl status mongod Restart if needed: sudo systemctl restart mysql sudo systemctl restart mongod
  3. Check if LMS & Studio Services are Running sudo /edx/bin/supervisorctl status
  4. Check for Errors in Logs sudo tail -f /edx/var/log/lms/edx.log

3. Login Issues (OAuth, JWT, Social Auth)

Possible Causes

✅ OAuth client misconfiguration
✅ Incorrect JWT_SECRET_KEY
✅ Expired authentication tokens

Fixes

  1. Check OAuth Client in Admin Panel
    • Go to /admin/oauth2/client/
    • Ensure redirect URI matches: https://your-lms.com/oauth2/login/
  2. Regenerate JWT Secret Keyopenssl rand -hex 32
    • Copy the output and update lms.env.json: "JWT_SECRET_KEY": "new-generated-key"
  3. Clear Django Sessions sudo -u www-data /edx/bin/python.edxapp manage.py shell from django.contrib.sessions.models import Session Session.objects.all().delete() exit()

4. Video Playback Issues

Possible Causes

✅ Incorrect video file format
✅ Video storage misconfiguration
✅ CDN or S3 settings issue

Fixes

  1. Check if Videos are Available ls /edx/var/edxapp/uploads/
  2. Enable Video Streaming
    • Go to Studio > Advanced Settings
    • Set: "course_video_upload_storage_base_url": "https://your-video-url.com"
  3. Check Video Transcripts ls /edx/var/edxapp/uploads/transcripts/
  4. Use MP4/HLS Formats
    • Convert videos to HLS (.m3u8) for better playback.

5. Course Content Not Loading

Possible Causes

✅ Database issues
✅ Corrupt content files
✅ Caching problems

Fixes

  1. Check Database Connectivity mysql -u root -p SHOW DATABASES;
  2. Manually Sync Course Data sudo -u www-data /edx/bin/python.edxapp manage.py cms sync_course --all
  3. Rebuild Course Index sudo -u www-data /edx/bin/python.edxapp manage.py cms reindex_course
  4. Clear Course Cache sudo rm -rf /edx/var/cache/course_structure/*

6. Discussion Forums Not Working

Possible Causes

✅ Forum service (forum) not running
✅ MongoDB connection issue

Fixes

  1. Check Forum Service Status sudo /edx/bin/supervisorctl status forum
  2. Restart Forum Service sudo /edx/bin/supervisorctl restart forum
  3. Check MongoDB Connection mongo use cs_comments_service db.stats()

7. Email Notifications Not Working

Possible Causes

✅ Incorrect SMTP settings
✅ Email queue failure

Fixes

  1. Verify SMTP Configuration
    • Edit lms.env.json: "EMAIL_HOST": "smtp.gmail.com", "EMAIL_PORT": 587, "EMAIL_USE_TLS": true, "EMAIL_HOST_USER": "your-email@gmail.com", "EMAIL_HOST_PASSWORD": "your-app-password"
  2. Check Email Queue sudo tail -f /edx/var/log/lms/edx.log | grep email
  3. Send a Test Email sudo -u www-data /edx/bin/python.edxapp manage.py lms sendtestemail test@example.com

8. Performance Issues (Slow Loading, High CPU Usage)

Possible Causes

✅ High server load
✅ Lack of caching
✅ Database performance issues

Fixes

  1. Check CPU & Memory Usage top
  2. Enable Caching
    • Install and enable Redis: sudo apt install redis-server
    • Edit lms.env.json: "CACHES": { "default": { "BACKEND": "django_redis.cache.RedisCache", "LOCATION": "redis://127.0.0.1:6379/1" } }
  3. Optimize Database mysql -u root -p -e "OPTIMIZE TABLE edxapp.courseware_studentmodule;"
  4. Restart Services sudo /edx/bin/supervisorctl restart all

9. SSL Certificate Issues

Possible Causes

✅ Expired SSL certificate
✅ Incorrect Nginx configuration

Fixes

  1. Renew SSL Certificate (Let’s Encrypt) sudo certbot renew sudo systemctl restart nginx
  2. Check Nginx SSL Configuration
    • Ensure ssl_certificate and ssl_certificate_key are correctly set in: /etc/nginx/sites-available/lms

Conclusion

This guide covers common Open edX issues related to LMS, Studio, video playback, authentication, performance, and SSL. If you encounter persistent issues, Open edX logs are your best debugging tool.