Skip to main content

Troubleshooting Guide

Common issues and solutions for the SmartRunning Training Optimization Platform.

Runner Creation & Onboarding Issues​

Missing Default Values (PBs, Heart Rate Zones)​

Symptoms: New runners created through onboarding have no PB values or performance metrics

Solution: Fixed in latest version - all runner creation paths now use centralized runner_service.py

  • Ensures consistent defaults for personal bests across multiple distances
  • Auto-calculates performance metrics from default PBs
  • Applies heart rate zones based on age

JavaScript Errors on Onboarding Page​

Symptoms: Console errors like "Cannot set properties of null" on /onboarding

Solution: Fixed - app.js now skips initialization for onboarding page

  • Onboarding has its own JavaScript separate from main app
  • Defensive null checks added for all element references

MongoDB Connection Issues​

Connection Failed / Timeout​

Symptoms: Application fails to start, logs show "Failed to connect to MongoDB"

Solutions:

  1. Verify connection string in .env file

    # Check your .env file has:
    MONGO_CONNECTION_STRING=mongodb+srv://username:password@cluster.mongodb.net/
    DATABASE_NAME=your_database

  2. Check network connectivity

    # Test MongoDB connection
    ping cluster.mongodb.net

  3. IP Whitelisting: Your IP address may not be whitelisted

    • See MongoDB Setup for detailed IP whitelisting troubleshooting
    • Quick check: Get your IP from ipinfo.io/ip and verify it's in MongoDB Atlas Network Access

  4. Ensure MongoDB Atlas cluster is running

    • Log in to MongoDB Atlas
    • Check cluster status (should be green/active)

SSL/TLS Handshake Errors​

Symptoms: "SSL: CERTIFICATE_VERIFY_FAILED" or "TLS handshake failed"

Solutions:

  1. For Kubernetes/GKE deployments:

    • Verify Docker image includes ca-certificates and openssl packages
    • Ensure certifi Python package is in requirements.txt
    • See MongoDB Setup for production deployment troubleshooting

  2. For local Docker:

    • Usually handled automatically
    • If issue persists, rebuild: docker-compose build --no-cache

Authentication & Session Issues​

Login Fails in Production (GKE/Kubernetes)​

Symptoms: Login page loads correctly, but after entering credentials and clicking "Sign In", the page refreshes to blank with no error messages in browser console. Works locally but fails in cloud deployment.

Root Cause: Flask session cookies configured with SESSION_COOKIE_SECURE=True (required for HTTPS) but LoadBalancer/Ingress serving traffic over HTTP.

Solutions:

  1. Temporary Fix (HTTP-only deployment):

    • Set environment variable in deployment.yml: 
      env:
      - name: SESSION_COOKIE_SECURE
        value: "false"
    • Redeploy application
    • Warning: This disables secure cookie flag. Only use for testing or non-production environments.

  2. Production Fix (Recommended):

    • Configure HTTPS/TLS for your LoadBalancer or Ingress: 
      # Example Ingress with TLS
      apiVersion: networking.k8s.io/v1
      kind: Ingress
      metadata:
        name: smartrunning-ingress
        annotations:
          kubernetes.io/ingress.class: "nginx"
          cert-manager.io/cluster-issuer: "letsencrypt-prod"
      spec:
        tls:
        - hosts:
          - your-domain.com
          secretName: smartrunning-tls
    • Set SESSION_COOKIE_SECURE=true in deployment configuration
    • Verify browser DevTools > Application > Cookies shows Secure flag

  3. CORS Configuration:

    • Ensure CORS is configured with credentials support (already implemented in app/__init__.py): 
      CORS(app, supports_credentials=True, resources={
          r"/*": {"origins": "*", "methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"]}
      })

Related Files:

  • app/config.py - Session cookie configuration (line 38)
  • deployment.yml - Environment variables for Kubernetes deployment
  • app/__init__.py - CORS configuration (line 59)

Verification:

  1. Check browser DevTools > Network > /auth/login response
  2. Verify Set-Cookie header is present in response
  3. Check Application > Cookies to see if session cookie is stored
  4. If cookie has Secure flag but site uses HTTP, login will fail silently

Session Expires Too Quickly​

Symptoms: User is logged out after short period of inactivity

Solutions:

  1. Increase session timeout in .env or deployment.yml:

    env:
    - name: SESSION_TIMEOUT_HOURS
      value: "24"  # Default is 8 hours

  2. Enable "Remember Me" checkbox on login page for 30-day persistent sessions

CORS Errors During Login​

Symptoms: Browser console shows "CORS policy: No 'Access-Control-Allow-Origin' header"

Solutions:

  1. Verify CORS is enabled in app/__init__.py with supports_credentials=True
  2. Check that frontend and backend are using the same protocol (both HTTP or both HTTPS)
  3. If using custom domain, update CORS origins list to include your domain

Docker Issues​

Container Won't Start​

Symptoms: docker compose up fails or containers exit immediately

Solutions:

  1. Clear existing containers and volumes

    docker-compose down -v

  2. Rebuild containers without cache

    docker-compose build --no-cache
    docker-compose up

  3. Check Docker logs for specific errors

    docker-compose logs -f web

  4. Verify Docker Desktop is running and has sufficient resources

    • Recommended: 4GB RAM minimum, 2 CPUs

Port Already in Use​

Symptoms: "Error starting userland proxy: Bind for 0.0.0.0:[port] failed: port is already allocated"

Solutions:

  1. Find and kill process using the configured port

    # On macOS/Linux
    lsof -ti:[port] | xargs kill -9

    # On Windows
    netstat -ano | findstr :[port]
    taskkill /PID [PID] /F

  2. Change port in docker-compose.yml if needed

    ports:
      - "[external_port]:5000"  # Use different external port

File Upload Issues​

Understanding Upload Workflow (Important!)​

How It Works:

  • Uploads are fully asynchronous - files are saved and processing happens in the background
  • Upload completes in less than 1 second, then you see: "Files uploaded successfully. Processing in background..."
  • No need to wait - you can navigate away or close the browser
  • Processing continues in background: unzip, convert, analyze, update history
  • Check the background jobs banner (top of page) for processing status
  • New sessions appear automatically once processing completes (refresh page if needed)

What to Expect:

  1. Upload FIT/ZIP file(s)
  2. See immediate confirmation message
  3. Background jobs banner appears showing processing status
  4. Banner disappears when complete (usually 30 seconds to few minutes depending on file size)
  5. Refresh page to see new sessions in calendar/list

Common Misunderstanding:

  • "Upload says complete but I don't see sessions", Processing still running in background, wait for banner to disappear
  • "Where's the progress bar?", No progress bar needed, background jobs banner shows status
  • "Is it stuck?", No, processing continues even if you navigate away or refresh

File Too Large​

Symptoms: Upload fails with "413 Payload Too Large" or "File exceeds maximum size"

Solutions:

  1. Check file size (default limit: 16MB)

    # Check file size
    ls -lh yourfile.fit

  2. Increase limit in .env if needed

    MAX_CONTENT_LENGTH=33554432  # 32MB in bytes

  3. Restart application after changing .env

Invalid File Format​

Symptoms: Upload succeeds but processing fails, error logs show "Invalid FIT file"

Solutions:

  1. Verify file format

    • Accepted: .fit files or .zip archives containing .fit files
    • File must be a valid Garmin FIT file

  2. Check file isn't corrupted

    • Try uploading a different FIT file
    • Re-export from Garmin Connect

  3. Check file encoding

    • FIT files should be binary, not text
    • File size should be > 0 bytes

Upload Directory Permissions​

Symptoms: "Permission denied" errors when uploading files

Solutions:

  1. For Docker: Check volume permissions in docker-compose.yml

    volumes:
      - ./data/uploads:/app/data/uploads

  2. For local development: Ensure upload directory exists and is writable

    mkdir -p data/uploads
    chmod 755 data/uploads

Session Processing Issues​

Background Job Stuck​

Symptoms: FIT file uploaded but never appears in sessions list

Solutions:

  1. Check background job status

    • View background jobs in admin dashboard at /admin
    • Look for jobs with status "failed" or "pending"

  2. Check application logs for processing errors

    docker-compose logs -f web | grep "ERROR"

  3. Restart application to reset job queue

    docker-compose restart

Statistics Not Calculated​

Symptoms: Session appears but has no statistics (HR zones, pace, etc.)

Solutions:

  1. Verify FIT file contains required data

    • Must have heart rate data for HR zone calculations
    • Must have GPS/distance data for pace calculations

  2. Check if Critical Speed is calculated for runner

    • Required for rTSS calculation
    • Navigate to runner profile and verify CS values exist

  3. Manually trigger statistics recalculation

    • Delete and re-upload the FIT file
    • Or use admin tools to reprocess session

Training Plan Issues​

Plan Generation Fails​

Symptoms: "Failed to generate training plan" error

Solutions:

  1. Verify runner has required data

    • Personal best times for tracked distances
    • Performance metrics calculated
    • Heart rate zones configured

  2. Check training plan schema is valid

    • View in admin dashboard at /admin
    • Ensure schema has at least one block with workouts

  3. Verify target date is in the future

    • Marathon date must be later than today

Plan Days Not Displaying​

Symptoms: Training plan created but calendar is empty

Solutions:

  1. Check trainingplan collection in database

    // In MongoDB, verify documents exist:
    db.trainingplan.find({ trainingplanID: "your-plan-id" }).count()

  2. Verify browser console for JavaScript errors

    • Open DevTools (F12)
    • Check Console tab for errors

  3. Clear browser cache and reload

    # Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)

Performance Issues​

Slow Session Loading​

Symptoms: Sessions list takes long time to load

Solutions:

  1. Large dataset: If runner has 500+ sessions, loading time increases

    • This is expected behavior for large datasets
    • The system processes all sessions for display

  2. Database indexes: Verify indexes are in place per Database Schema

    // Performance indexes:
    db.sessionsFIT.createIndex({ runner_id: 1, uploaded_at: -1 })
    db.sessionStatistics.createIndex({ runner_id: 1, processed_timestamp: -1 })

Slow Chart Rendering​

Symptoms: Training load charts render slowly or freeze browser

Solutions:

  1. Reduce date range

    • Load smaller time periods (e.g., last 3 months instead of all time)

  2. Check runnerHistory collection size

    db.runnerHistory.find({ runner_id: ObjectId(...) }).count()

  3. For large datasets, reduce the display window

    • Use date range filters to limit data points

Development Issues​

Python Import Errors​

Symptoms: ModuleNotFoundError when running locally

Solutions:

  1. Ensure virtual environment is activated

    source venv/bin/activate  # macOS/Linux
    venv\Scripts\activate     # Windows

  2. Install dependencies

    pip install -r requirements.txt

  3. Verify Python version

    python --version  # Should be 3.11-3.13

MongoDB Connection Works Locally But Not in Kubernetes​

Symptoms: Application runs fine locally but fails when deployed to GKE

Solutions:

  1. Most common cause: IP whitelisting

    • See MongoDB Setup for detailed Kubernetes network troubleshooting
    • GKE egress IP is different from LoadBalancer IP

  2. Check environment variables in Kubernetes

    kubectl get configmap
    kubectl describe configmap <name>

Still Having Issues?​

If your problem isn't listed here:

  1. Check application logs:

    # Docker
    docker-compose logs -f web

    # Kubernetes
    kubectl logs deployment/smartrunning-localapp --tail=50

  2. Check MongoDB logs in MongoDB Atlas UI

  3. Verify environment configuration:

    # Ensure all required variables are set
    cat .env | grep -v '^#' | grep -v '^$'

  4. Search for similar issues in project documentation:

  5. Contact support with:

    • Detailed error message
    • Steps to reproduce
    • Environment (local Docker / Kubernetes / local Python)
    • Relevant log excerpts