LEDMatrix/docs/archive/WEB_INTERFACE_TROUBLESHOOTING.md

Web Interface Troubleshooting Guide

Quick Diagnosis Steps

Since the web interface doesn't seem to run and shows no logging after reorganization, follow these steps on your Raspberry Pi to diagnose the issue:

1. Check Service Status

# Check if the web service is running
sudo systemctl status ledmatrix-web

# Check if it's enabled to start on boot
sudo systemctl is-enabled ledmatrix-web

2. View Service Logs

The service logs to syslog, not stdout. Use these commands to view logs:

# View recent web interface logs
sudo journalctl -u ledmatrix-web -n 50 --no-pager

# Follow logs in real-time
sudo journalctl -u ledmatrix-web -f

# View logs since last boot
sudo journalctl -u ledmatrix-web -b

3. Check Configuration

# Check if web_display_autostart is enabled in config
cat ~/LEDMatrix/config/config.json | grep web_display_autostart

# Should show: "web_display_autostart": true

If it shows false or is missing, the web interface won't start (by design).

4. Test Manual Startup

Try starting the web interface manually to see error messages:

cd ~/LEDMatrix
python3 web_interface/start.py

This will show any import errors or startup issues directly in the terminal.

Common Issues and Solutions

Issue 1: Service Not Running

Symptom: systemctl status ledmatrix-web shows "inactive (dead)"

Solutions:

# Start the service
sudo systemctl start ledmatrix-web

# Enable it to start on boot
sudo systemctl enable ledmatrix-web

# Check status again
sudo systemctl status ledmatrix-web

Issue 2: web_display_autostart is False

Symptom: Service starts but immediately exits gracefully

Solution:

# Edit config.json
nano ~/LEDMatrix/config/config.json

# Set web_display_autostart to true:
"web_display_autostart": true

# Restart the service
sudo systemctl restart ledmatrix-web

Issue 3: Import Errors

Symptom: Service fails immediately with import errors in logs

Possible causes:

• Missing dependencies
• Python path issues
• Circular import problems

Solutions:

# Install/reinstall web dependencies
cd ~/LEDMatrix
pip3 install --break-system-packages -r web_interface/requirements.txt

# Check for Python errors
python3 -c "from web_interface.app import app; print('OK')"

Issue 4: Port Already in Use

Symptom: Error message about port 5000 being in use

Solution:

# Check what's using port 5000
sudo lsof -i :5000

# Kill the process if needed
sudo kill -9 <PID>

# Or change the port in web_interface/start.py

Issue 5: Permission Issues

Symptom: Permission denied errors in logs

Solution:

# Ensure proper ownership
cd ~/LEDMatrix
sudo chown -R ledpi:ledpi .

# Restart service
sudo systemctl restart ledmatrix-web

Issue 6: Flask/Blueprint Import Errors

Symptom: ImportError or ModuleNotFoundError in logs

Check these files exist:

ls -la ~/LEDMatrix/web_interface/app.py
ls -la ~/LEDMatrix/web_interface/start.py
ls -la ~/LEDMatrix/web_interface/blueprints/api_v3.py
ls -la ~/LEDMatrix/web_interface/blueprints/pages_v3.py

If any are missing, you may need to restore from git or the reorganization.

Detailed Logging Commands

View All Web Service Logs

# Show all logs with timestamps
sudo journalctl -u ledmatrix-web --no-pager

# Show logs from the last hour
sudo journalctl -u ledmatrix-web --since "1 hour ago"

# Show logs between specific times
sudo journalctl -u ledmatrix-web --since "2024-10-14 10:00:00" --until "2024-10-14 11:00:00"

# Show only errors
sudo journalctl -u ledmatrix-web -p err

Check Python Import Issues

cd ~/LEDMatrix

# Test imports step by step
python3 -c "import sys; sys.path.insert(0, '.'); from src.config_manager import ConfigManager; print('ConfigManager OK')"

python3 -c "import sys; sys.path.insert(0, '.'); from src.plugin_system.plugin_manager import PluginManager; print('PluginManager OK')"

python3 -c "import sys; sys.path.insert(0, '.'); from web_interface.app import app; print('Flask App OK')"

Service File Check

Verify the service file is correct:

cat /etc/systemd/system/ledmatrix-web.service

Should contain:

[Unit]
Description=LED Matrix Web Interface Service
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/home/ledpi/LEDMatrix
Environment=USE_THREADING=1
ExecStart=/usr/bin/python3 /home/ledpi/LEDMatrix/start_web_conditionally.py
Restart=on-failure
RestartSec=10
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=ledmatrix-web

[Install]
WantedBy=multi-user.target

If it's different or points to old paths, reinstall it:

cd ~/LEDMatrix
sudo bash install_web_service.sh
sudo systemctl daemon-reload
sudo systemctl restart ledmatrix-web

Post-Reorganization Checklist

Verify the reorganization completed correctly:

cd ~/LEDMatrix

# These files should exist in new locations:
ls web_interface/app.py
ls web_interface/start.py
ls web_interface/requirements.txt
ls web_interface/blueprints/api_v3.py
ls web_interface/blueprints/pages_v3.py

# start_web_conditionally.py should point to new location
grep "web_interface/start.py" start_web_conditionally.py

Emergency Recovery

If nothing works, you can rollback to the old structure:

cd ~/LEDMatrix

# Check git status
git status

# If changes aren't committed, revert
git checkout .

# Or restore specific files from old_web_interface
# (if that directory exists)

Recommended Diagnostic Sequence

Run these commands in order to get a complete picture:

#!/bin/bash
echo "=== Web Interface Diagnostic Report ==="
echo ""
echo "1. Service Status:"
sudo systemctl status ledmatrix-web
echo ""
echo "2. Config Autostart Setting:"
cat ~/LEDMatrix/config/config.json | grep web_display_autostart
echo ""
echo "3. Recent Logs (last 20 lines):"
sudo journalctl -u ledmatrix-web -n 20 --no-pager
echo ""
echo "4. File Structure Check:"
ls -la ~/LEDMatrix/web_interface/
echo ""
echo "5. Python Import Test:"
cd ~/LEDMatrix
python3 -c "from web_interface.app import app; print('✓ Flask app imports successfully')" 2>&1
echo ""
echo "=== End of Diagnostic Report ==="

Save this as diagnose_web.sh, make it executable, and run it:

chmod +x diagnose_web.sh
./diagnose_web.sh

Success Indicators

When the web interface is running correctly, you should see:

1. Service Status: "active (running)" in green
2. Logs: "Starting LED Matrix Web Interface V3..."
3. Network: Accessible at http://<pi-ip>:5000
4. Process: Python process listening on port 5000

# Check if it's listening
sudo netstat -tlnp | grep :5000
# or
sudo ss -tlnp | grep :5000

Contact/Help

If you've tried all these steps and it still doesn't work, collect the following information:

1. Output from the diagnostic script above
2. Full service logs: sudo journalctl -u ledmatrix-web -n 100 --no-pager
3. Output from manual startup attempt
4. Git status and recent commits

This will help identify the exact issue.