Skip to main content

​
Overview

This page covers common issues you may encounter when setting up or running Platzi Viewer, along with their solutions.

​
Cache Loading Issues

Error Message:
[ERROR] courses_cache.json no encontrado.
   Ejecuta: python rebuild_cache_drive.py
Cause: The application requires a pre-built cache file that maps course structures to Google Drive file IDs.Solution:
  1. Run the cache builder: 
    python rebuild_cache_drive.py
  2. Wait 15-30 minutes for the initial scan to complete
  3. The script will create courses_cache.json (~20MB)
Note: If the scan is interrupted, you can resume it by running the command again. Progress is saved in drive_scan_progress.json.
Error Message:
[WARN] Cache inválido en [path]: courses_cache.json inválido: schema básico no cumple
Cause: The cache file is corrupted or was modified incorrectly.Solution:
  1. Delete the corrupted courses_cache.json file
  2. Rebuild the cache: 
    python rebuild_cache_drive.py
  3. Do not manually edit the cache file
Symptom: Changes to Drive content don’t appear in the app.Solution:
  1. Access the refresh endpoint (only works from localhost): 
    http://localhost:8080/api/refresh
  2. The server will reload the cache in the background
  3. Refresh your browser page
Alternative: Restart the server:
# Stop the server (Ctrl+C)
python server.py
Symptom: Server crashes or runs out of memory.Cause: The ~20MB courses_cache.json file is loaded entirely into RAM.Solution:
  • Ensure your system has at least 512MB of available RAM
  • Close other memory-intensive applications
  • For systems with limited resources, consider reducing the number of courses in PlatziRoutes.md before rebuilding the cache
Note: A future version will implement lazy loading to reduce memory usage.

​
Port and Network Issues

Error Message:
OSError: [Errno 48] Address already in use
or
OSError: [WinError 10048] Only one usage of each socket address
Cause: Another application is using port 8080.Solution 1 - Use a different port:
# Windows PowerShell
$env:PORT="8090"
python server.py

# Linux/Mac
PORT=8090 python server.py
Solution 2 - Find and stop the conflicting process:
# Windows
netstat -ano | findstr :8080
taskkill /PID <pid> /F

# Linux/Mac
lsof -i :8080
kill <pid>
Symptom: Connection refused or timeout when accessing http://localhost:8080.Check list:
  1. Verify the server is running (you should see “Servidor listo” message)
  2. Check the correct port is being used
  3. Ensure no firewall is blocking the connection
  4. Try accessing via http://127.0.0.1:8080 instead
For custom bind addresses:
# Bind to all interfaces
HOST=0.0.0.0 python server.py
Binding to 0.0.0.0 allows external network access. Only use this on trusted networks.

​
Python Dependencies

Error Message:
ModuleNotFoundError: No module named 'google.oauth2'
ModuleNotFoundError: No module named 'googleapiclient'
Cause: Required Python packages are not installed.Solution:
# Activate virtual environment
# Windows:
.venv\Scripts\activate
# Linux/Mac:
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt
Key dependencies:
  • google-api-python-client - Drive API client
  • google-auth - Authentication
  • google-auth-httplib2 - HTTP transport
Requirement: Python 3.7 or higherCheck your version:
python --version
If you have an older version:
  • Download Python 3.7+ from python.org
  • Update your system Python using your package manager
  • Use python3 instead of python on some systems

​
Progress Data Issues

Symptom: Course progress resets after closing the browser.Causes and solutions:
  1. Browser storage disabled:
    • Enable cookies and local storage in browser settings
    • Don’t use private/incognito mode
  2. progress.json write error:
    • Check server console for permission errors
    • Ensure the server has write access to the data directory
    • Verify DATA_PATH environment variable if set
  3. Payload too large:
    • Default limit: 2MB
    • Error: {"error": "payload_too_large"}
    • Increase limit: MAX_PROGRESS_BYTES=4194304 python server.py
Symptom: Server returns empty progress or errors when loading.Solution:
  1. Stop the server
  2. Backup the file: 
    cp progress.json progress.json.backup
  3. Try to fix JSON syntax errors manually, or delete the file: 
    rm progress.json
  4. Restart the server
Note: Progress is stored in both localStorage (browser) and progress.json (server backup).

​
Desktop App Issues

Symptom: Nothing happens when double-clicking PlatziViewer.exe or PlatziViewerDesktop.exe.Solutions:
  1. Missing files:
    • Ensure courses_cache.json is in the same folder as the .exe
    • Ensure service_account.json is present (if not using env variables)
  2. Antivirus blocking:
    • Add the .exe to your antivirus exclusions
    • Some antivirus software blocks unsigned executables
  3. Run from Command Prompt to see errors: 
    cd path\to\PlatziViewer
PlatziViewer.exe
Requirements:
  • PyInstaller installed: pip install pyinstaller
  • All dependencies installed: pip install -r requirements.txt
Build commands:Web version (browser-based):
powershell -ExecutionPolicy Bypass -File .\build_portable_exe.ps1
Output: dist/PlatziViewer/PlatziViewer.exeDesktop version (standalone window):
powershell -ExecutionPolicy Bypass -File .\build_desktop_exe.ps1
Output: dist/PlatziViewerDesktop.exeBefore distributing:
  • Copy courses_cache.json to dist/PlatziViewer/
  • Optionally copy service_account.json (or use environment variables)

​
Health Check Endpoint

Use the health endpoint to diagnose server issues: 
http://localhost:8080/api/health
Response format: 
{
  "status": "ok",
  "drive": {
    "available": true,
    "error": null
  },
  "ffmpeg": {
    "available": true,
    "path": "/usr/bin/ffmpeg"
  },
  "compatStream": {
    "totalRequests": 5,
    "successfulStreams": 4,
    "failedStreams": 1,
    "lastMode": "copy",
    "lastError": null
  }
}
Interpreting the response:

​
Docker Issues

Error: "drive": {"available": false}Check /api/health response for details.Common causes:
  1. Service account file not mounted: 
    # docker-compose.yml
volumes:
  - ./secrets/service_account.json:/app/service_account.json:ro
  2. Environment variable not set: 
    environment:
  - GOOGLE_SERVICE_ACCOUNT_FILE=/app/service_account.json
    or 
    environment:
  - GOOGLE_SERVICE_ACCOUNT_JSON=${GOOGLE_SERVICE_ACCOUNT_JSON}
  3. Wrong file path in container:
    • Check that the mounted path matches GOOGLE_SERVICE_ACCOUNT_FILE
    • Use absolute paths in environment variables
Symptom: Cache resets when container restarts.Solution: Mount a volume for persistent data:
# docker-compose.yml
volumes:
  - ./runtime-data:/app/data
environment:
  - PLATZI_DATA_PATH=/app/data

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us