LEDMatrix/wiki/MILB_TROUBLESHOOTING.md

MiLB Manager Troubleshooting Guide

Issue Summary

The MiLB manager is no longer pulling accurate game information due to several factors, primarily the current offseason period.

Root Causes

1. Primary Issue: MiLB Offseason

• Problem: MiLB season runs from April to September
• Current Status: We're in January 2025 (offseason)
• Impact: No regular season games are scheduled during offseason
• Solution: Enable test mode for offseason testing

2. Secondary Issues

• API Endpoint Changes: MLB Stats API endpoints may have changed
• Sport ID Updates: Some sport IDs might be outdated
• Team Mapping: Team abbreviations may have changed

Solutions Implemented

Immediate Fix: Enable Test Mode

{
    "milb": {
        "test_mode": true
    }
}

Code Improvements

1. Season Awareness: Added offseason detection
2. Better Logging: More informative error messages
3. Test Mode Enhancement: Improved test data

Diagnostic Tools Created

1. Basic API Test

python test/test_milb_api.py

2. Comprehensive Diagnostic

python test/diagnose_milb_issues.py

Testing the Fixes

Step 1: Run Diagnostic

cd /path/to/LEDMatrix
python test/diagnose_milb_issues.py

Step 2: Test with Test Mode

1. Ensure test_mode: true in config
2. Restart the display system
3. Check if test games appear

Step 3: Verify API (When Season Returns)

python test/test_milb_api.py

Expected Behavior

During Offseason (October-March)

• No real games found
• Test mode shows sample games
• Logs indicate offseason status

During Season (April-September)

• Real games should be found
• Live games display correctly
• Upcoming games show properly

Configuration Options

Test Mode

{
    "milb": {
        "test_mode": true,
        "enabled": true
    }
}

Season Override (For Testing)

{
    "milb": {
        "test_mode": true,
        "force_season": true
    }
}

Common Issues and Solutions

Issue: No Games Found

• Cause: Offseason or API issues
• Solution: Enable test mode

Issue: API Errors

• Cause: Network or endpoint issues
• Solution: Check internet connection and API status

Issue: Wrong Team Names

• Cause: Team mapping outdated
• Solution: Update milb_team_mapping.json

Issue: Wrong Sport IDs

• Cause: MLB API changes
• Solution: Update sport IDs in config

Monitoring and Logs

Key Log Messages

• "MiLB is currently in offseason" - Normal during offseason
• "Using test mode data for MiLB" - Test mode active
• "No games returned from API" - API issue or offseason

Debug Mode

Enable debug logging to see detailed API calls:

logger.setLevel(logging.DEBUG)

Future Improvements

Planned Enhancements

1. Season Schedule Integration: Use official season dates
2. API Fallback: Multiple API endpoints
3. Caching Improvements: Better cache management
4. Error Recovery: Automatic retry mechanisms

Configuration Enhancements

{
    "milb": {
        "season_start_month": 4,
        "season_end_month": 9,
        "api_fallback": true,
        "cache_duration": 3600
    }
}

Contact and Support

For additional issues:

1. Run the diagnostic tools
2. Check the logs for specific errors
3. Verify network connectivity
4. Test API endpoints directly

Quick Reference

Enable Test Mode

# Edit config/config.json
# Change "test_mode": false to "test_mode": true

Run Diagnostics

python test/diagnose_milb_issues.py

Test API Directly

python test/test_milb_api.py

Check Season Status

• April-September: Season active
• October-March: Offseason (use test mode)