LEDMatrix/docs/PLUGIN_DEPENDENCY_TROUBLESHOOTING.md

Plugin Dependency Installation Troubleshooting

This guide helps resolve issues with automatic plugin dependency installation in the LEDMatrix system.

Common Error Symptoms

Permission Errors

ERROR: Could not install packages due to an OSError: [Errno 13] Permission denied: '/root/.local'
WARNING: The directory '/root/.cache/pip' or its parent directory is not owned or is not writable

Context Mismatch

WARNING: Installing plugin dependencies for current user (not root). 
These will NOT be accessible to the systemd service.

Root Cause

Plugin dependencies must be installed in a context accessible to the LEDMatrix systemd service, which runs as root. Permission errors typically occur when:

1. The pip cache directory has incorrect permissions
2. The process tries to install to user directories without proper permissions
3. Environment variables (like HOME) are not set correctly for the service context

Solutions

Solution 1: Use the Manual Installation Script (Recommended)

We provide a helper script that handles dependency installation correctly:

# Run as root to install system-wide (for production)
sudo /home/ledpi/LEDMatrix/scripts/install_plugin_dependencies.sh

# After installation, restart the service
sudo systemctl restart ledmatrix

This script:

• Detects all plugins with requirements.txt files
• Installs dependencies with correct permissions
• Uses --no-cache-dir to avoid cache permission issues
• Provides detailed logging for troubleshooting

Solution 2: Manual Installation per Plugin

If you need to install dependencies for a specific plugin:

# Navigate to the plugin directory
cd /home/ledpi/LEDMatrix/plugins/PLUGIN-NAME

# Install as root (system-wide)
sudo pip3 install --break-system-packages --no-cache-dir -r requirements.txt

# Restart the service
sudo systemctl restart ledmatrix

Solution 3: Fix Cache Directory Permissions

If you specifically have cache permission issues:

# Option A: Skip the cache (recommended)
sudo pip3 install --no-cache-dir --break-system-packages -r requirements.txt

# Option B: Fix cache permissions (if needed)
sudo mkdir -p /root/.cache/pip
sudo chown -R root:root /root/.cache
sudo chmod -R 755 /root/.cache

Solution 4: Install via Web Interface

The web interface handles dependency installation correctly in the service context:

1. Access the web interface (http://ledpi:5000 or http://your-pi-ip:5000)
2. Open the Plugin Manager tab (use the Plugin Store section to find the plugin, or Install from GitHub)
3. Install the plugin through the web UI
4. The system automatically handles dependency installation in the service context (which has the right permissions)

Prevention

For Plugin Developers

When creating plugins with dependencies:

1. Keep requirements minimal: Only include essential packages
2. Test installation: Verify your requirements.txt works with:

   sudo pip3 install --break-system-packages --no-cache-dir -r requirements.txt
   

3. Document dependencies: Note any system packages needed (via apt)

For Users

1. Use web interface: Install plugins via the web UI when possible
2. Install as root: When using SSH/terminal, use sudo for plugin installations
3. Restart service: After manual installations, restart the ledmatrix service

Technical Details

How Dependency Installation Works

The PluginManager._install_plugin_dependencies() method:

1. Detects if running as root using os.geteuid() == 0
2. If root: Uses system-wide installation with --break-system-packages --no-cache-dir
3. If not root: Uses user installation with --user --break-system-packages --no-cache-dir
4. The --no-cache-dir flag prevents cache-related permission issues

Why --break-system-packages?

Debian 12+ (Bookworm) and Raspberry Pi OS based on it implement PEP 668, which prevents pip from installing packages system-wide by default. The --break-system-packages flag overrides this protection, which is necessary for the plugin system.

Service Context

The ledmatrix.service runs as:

• User: root
• WorkingDirectory: /home/ledpi/LEDMatrix
• Python: /usr/bin/python3

Dependencies must be installed in root's Python environment or system-wide to be accessible.

Checking Installation

Verify dependencies are installed correctly:

# Check as root (how the service sees it)
sudo python3 -c "import package_name"

# List installed packages
pip3 list

# Check specific package
pip3 show package_name

Getting Help

If you continue to experience issues:

1. Check the service logs:

   sudo journalctl -u ledmatrix -f
   

2. Check pip logs (created by manual script):

   cat /tmp/pip_install_*.log
   

3. Verify plugin manifest is correct:

   cat /home/ledpi/LEDMatrix/plugins/PLUGIN-NAME/manifest.json
   

4. Check plugin requirements:

   cat /home/ledpi/LEDMatrix/plugins/PLUGIN-NAME/requirements.txt
   

Related Documentation

• Plugin Dependency Guide
• Plugin Development Guide
• Troubleshooting