LEDMatrix/docs/PLUGIN_ERROR_HANDLING.md

Plugin Error Handling Guide

This guide covers best practices for error handling in LEDMatrix plugins.

Custom Exception Hierarchy

LEDMatrix provides typed exceptions for different error categories. Use these instead of generic Exception:

from src.exceptions import PluginError, ConfigError, CacheError, DisplayError

# Plugin-related errors
raise PluginError("Failed to fetch data", plugin_id=self.plugin_id, context={"api": "ESPN"})

# Configuration errors
raise ConfigError("Invalid API key format", field="api_key")

# Cache errors
raise CacheError("Cache write failed", cache_key="game_data")

# Display errors
raise DisplayError("Failed to render", display_mode="live")

Exception Context

All LEDMatrix exceptions support a context dict for additional debugging info:

raise PluginError(
    "API request failed",
    plugin_id=self.plugin_id,
    context={
        "url": api_url,
        "status_code": response.status_code,
        "retry_count": 3
    }
)

Logging Best Practices

Use the Plugin Logger

Every plugin has access to self.logger:

class MyPlugin(BasePlugin):
    def update(self):
        self.logger.info("Starting data fetch")
        self.logger.debug("API URL: %s", api_url)
        self.logger.warning("Rate limit approaching")
        self.logger.error("API request failed", exc_info=True)

Log Levels

• DEBUG: Detailed info for troubleshooting (API URLs, parsed data)
• INFO: Normal operation milestones (plugin loaded, data fetched)
• WARNING: Recoverable issues (rate limits, cache miss, fallback used)
• ERROR: Failures that need attention (API down, display error)

Include exc_info for Exceptions

try:
    response = requests.get(url)
except requests.RequestException as e:
    self.logger.error("API request failed: %s", e, exc_info=True)

Error Handling Patterns

Never Use Bare except

# BAD - swallows all errors including KeyboardInterrupt
try:
    self.fetch_data()
except:
    pass

# GOOD - catch specific exceptions
try:
    self.fetch_data()
except requests.RequestException as e:
    self.logger.warning("Network error, using cached data: %s", e)
    self.data = self.get_cached_data()

Graceful Degradation

def update(self):
    try:
        self.data = self.fetch_live_data()
    except requests.RequestException as e:
        self.logger.warning("Live data unavailable: %s", e)
        # Fall back to cache
        cached = self.cache_manager.get(self.cache_key)
        if cached:
            self.logger.info("Using cached data")
            self.data = cached
        else:
            self.logger.error("No cached data available")
            self.data = None

Validate Configuration Early

def validate_config(self) -> bool:
    """Validate configuration at load time."""
    api_key = self.config.get("api_key")
    if not api_key:
        self.logger.error("api_key is required but not configured")
        return False

    if not isinstance(api_key, str) or len(api_key) < 10:
        self.logger.error("api_key appears to be invalid")
        return False

    return True

Handle Display Errors

def display(self, force_clear: bool = False) -> bool:
    if not self.data:
        if force_clear:
            self.display_manager.clear()
            self.display_manager.update_display()
        return False

    try:
        self._render_content()
        return True
    except Exception as e:
        self.logger.error("Display error: %s", e, exc_info=True)
        # Clear display on error to prevent stale content
        self.display_manager.clear()
        self.display_manager.update_display()
        return False

Error Aggregation

LEDMatrix automatically tracks plugin errors: every exception or timeout from a plugin's update() or display() is recorded by the display service, which runs the plugins. See them in the web interface under Logs → Plugin errors, or through the API:

# Get error summary
curl http://localhost:5000/api/v3/errors/summary

# Get plugin-specific health
curl http://localhost:5000/api/v3/errors/plugin/my-plugin

# Clear errors older than 24 hours (the default), or all of them
curl -X POST http://localhost:5000/api/v3/errors/clear
curl -X POST -H 'Content-Type: application/json' -d '{"all": true}' \
  http://localhost:5000/api/v3/errors/clear

The web interface is a separate process, so it reads a snapshot the display service writes to the shared cache directory (plugin_error_snapshot): at most every 10 seconds, and only when something changed. Expect the numbers to lag by up to about 15 seconds, and to start from zero when the display service restarts. snapshot_available is false until the display service has reported. A clear is a request the display service applies within about 5 seconds; the API hides the cleared errors immediately. Details and response shapes: REST API reference.

Error Patterns

When the same error occurs repeatedly (5+ times in 60 minutes), it's detected as a pattern and logged as a warning. This helps identify systemic issues.

Common Error Scenarios

API Rate Limiting

def fetch_data(self):
    try:
        response = requests.get(self.api_url)
        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 60))
            self.logger.warning("Rate limited, retry after %ds", retry_after)
            self._rate_limited_until = time.time() + retry_after
            return None
        response.raise_for_status()
        return response.json()
    except requests.RequestException as e:
        self.logger.error("API error: %s", e)
        return None

Timeout Handling

def fetch_data(self):
    try:
        response = requests.get(self.api_url, timeout=10)
        return response.json()
    except requests.Timeout:
        self.logger.warning("Request timed out, will retry next update")
        return None
    except requests.RequestException as e:
        self.logger.error("Request failed: %s", e)
        return None

Missing Data Gracefully

def get_team_logo(self, team_id):
    logo_path = self.logos_dir / f"{team_id}.png"
    if not logo_path.exists():
        self.logger.debug("Logo not found for team %s, using default", team_id)
        return self.default_logo
    return Image.open(logo_path)

Testing Error Handling

def test_handles_api_error(mock_requests):
    """Test plugin handles API errors gracefully."""
    mock_requests.get.side_effect = requests.RequestException("Network error")

    plugin = MyPlugin(...)
    plugin.update()

    # Should not raise, should log warning, should have no data
    assert plugin.data is None

def test_handles_invalid_json(mock_requests):
    """Test plugin handles invalid JSON response."""
    mock_requests.get.return_value.json.side_effect = ValueError("Invalid JSON")

    plugin = MyPlugin(...)
    plugin.update()

    assert plugin.data is None

Checklist

• No bare except: clauses
• All exceptions logged with appropriate level
• exc_info=True for error-level logs
• Graceful degradation with cache fallbacks
• Configuration validated in validate_config()
• Display clears on error to prevent stale content
• Timeouts configured for all network requests