Projektarbeit-MYP/backend/docs/COMMON_ERRORS.md

MYP Platform - Häufige Fehler und Lösungen

Dieses Dokument sammelt häufige Installations- und Konfigurationsfehler mit ihren bewährten Lösungen.

📦 Python-Paket-Installationsfehler

Send2Trash Installation schlägt fehl

Problem:

ERROR: Failed building wheel for Send2Trash
error: Microsoft Visual C++ 14.0 is required

Lösung:

• Send2Trash wurde aus requirements.txt entfernt
• Native Alternative in backend/utils/file_utils.py implementiert
• Verwendet plattformspezifische Papierkorb-APIs:
  • Windows: PowerShell + Visual Basic FileSystem
  • Linux: gio/gvfs-trash/XDG-Standard
  • macOS: osascript + Finder

Code-Ersatz:

# Alt:
from send2trash import send2trash
send2trash(file_path)

# Neu:
from utils.file_utils import move_to_trash
move_to_trash(file_path)

Python-magic-bin Windows-Fehler

Problem:

ERROR: Could not find a version that satisfies the requirement python-magic-bin

Lösung:

• Paket ist Windows-spezifisch und wird automatisch übersprungen auf Linux
• Setup-Skript erstellt bereinigte requirements.txt ohne problematische Pakete
• Plattformspezifische Conditional-Installation: ; sys_platform == "win32"

RPi.GPIO auf Non-Raspberry Pi

Problem:

RuntimeError: This module can only be run on a Raspberry Pi!

Lösung:

• Conditional-Installation: RPi.GPIO; sys_platform == "linux"
• Wird automatisch übersprungen wenn nicht auf Raspberry Pi
• Fallback-Hardware-Detection in Hardware-Modulen

🔧 Systemkonfigurationsfehler

Hostname-Änderung schlägt fehl

Problem:

hostnamectl: command not found
/etc/hostname: Permission denied

Lösung:

# Prüfe systemd-Verfügbarkeit
if command -v hostnamectl >/dev/null 2>&1; then
    sudo hostnamectl set-hostname m040tbaraspi001
else
    # Fallback für ältere Systeme
    echo "m040tbaraspi001" | sudo tee /etc/hostname
    sudo hostname m040tbaraspi001
fi

# Hosts-Datei aktualisieren
sudo sed -i 's/127.0.1.1.*/127.0.1.1\tm040tbaraspi001/' /etc/hosts

SSL-Zertifikat-Generierung schlägt fehl

Problem:

openssl: command not found
Permission denied: /opt/myp/ssl/

Lösung:

# OpenSSL installieren
sudo apt update && sudo apt install -y openssl

# Verzeichnis mit korrekten Berechtigungen erstellen
sudo mkdir -p /opt/myp/ssl
sudo chown -R $USER:$USER /opt/myp/ssl
sudo chmod 755 /opt/myp/ssl

# Self-signed Zertifikat generieren
openssl req -x509 -newkey rsa:4096 -keyout /opt/myp/ssl/key.pem \
    -out /opt/myp/ssl/cert.pem -days 365 -nodes \
    -subj "/C=DE/ST=NRW/L=Duesseldorf/O=Mercedes-Benz/CN=m040tbaraspi001"

Systemd-Service Installation schlägt fehl

Problem:

Failed to enable unit: Unit file does not exist
systemctl: command not found

Lösung:

# Prüfe systemd-Verfügbarkeit
if ! command -v systemctl >/dev/null 2>&1; then
    echo "systemd nicht verfügbar - verwende alternatives Init-System"
    # Fallback auf SysV init oder manuelle Autostart-Einrichtung
    return 1
fi

# Service-Datei kopieren und aktivieren
sudo cp myp-*.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable myp-app.service
sudo systemctl enable myp-kiosk.service

🌐 Netzwerkkonfigurationsfehler

Firewall blockiert Zugriff

Problem:

Connection refused: https://m040tbaraspi001.de040.corpintra.net:443
curl: (7) Failed to connect

Lösung:

# UFW-Firewall konfigurieren
sudo ufw allow 22/tcp     # SSH
sudo ufw allow 80/tcp     # HTTP
sudo ufw allow 443/tcp    # HTTPS
sudo ufw allow 5000/tcp   # Flask Development
sudo ufw --force enable

# iptables direkt (falls UFW nicht verfügbar)
sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT
sudo iptables-save | sudo tee /etc/iptables/rules.v4

DNS-Auflösung schlägt fehl

Problem:

nslookup: can't resolve 'm040tbaraspi001.de040.corpintra.net'
ping: unknown host

Lösung:

# Lokale hosts-Datei erweitern
echo "127.0.0.1    m040tbaraspi001.local" | sudo tee -a /etc/hosts
echo "127.0.0.1    m040tbaraspi001.de040.corpintra.net" | sudo tee -a /etc/hosts

# DNS-Server prüfen und setzen
echo "nameserver 8.8.8.8" | sudo tee -a /etc/resolv.conf
echo "nameserver 8.8.4.4" | sudo tee -a /etc/resolv.conf

# NetworkManager DNS (Ubuntu/Debian)
sudo systemctl restart NetworkManager

🖥️ Desktop- und Kiosk-Fehler

Graphical Session Target Not Found

Problem:

graphical session target not found
Unit graphical-session.target could not be found
Failed to start myp-kiosk.service

Ursache: Das graphical-session.target existiert nicht auf allen Raspberry Pi-Konfigurationen

🚀 SCHNELLE LÖSUNG:

# Super-Skript ausführen (behebt ALLES automatisch):
cd /opt/myp
sudo ./setup_https_only.sh

# Das Super-Skript erkennt und behebt automatisch:
# ✅ Graphical session target Problem
# ✅ Service-Konfiguration reparieren
# ✅ Korrekte Targets verwenden  
# ✅ Headless/Desktop-System automatisch erkennen

🔧 Manuelle Lösung:

# 1. Service-Datei anpassen
sudo systemctl edit myp-kiosk.service --full

# 2. Ersetze in der [Unit]-Sektion:
# VON: After=graphical-session.target
# ZU:  After=graphical.target

# 3. SystemD neu laden
sudo systemctl daemon-reload
sudo systemctl restart myp-kiosk

📋 Für verschiedene Szenarien:

# Headless-System (ohne Display):
sudo systemctl disable myp-kiosk

# Desktop-Environment installieren:
sudo apt install --no-install-recommends xserver-xorg xinit

# Graphical Target als Standard setzen:
sudo systemctl set-default graphical.target

# Verfügbare Targets prüfen:
systemctl list-unit-files --type=target | grep graphical

Chromium startet nicht im Kiosk-Modus

Problem:

chromium-browser: command not found
[ERROR:gpu_init.cc] GPU initialization failed

Lösung:

# Chromium installieren
sudo apt update && sudo apt install -y chromium-browser

# GPU-Acceleration deaktivieren für Headless-Systeme
chromium-browser --no-sandbox --disable-gpu --disable-software-rasterizer \
    --disable-background-timer-throttling --disable-renderer-backgrounding \
    --disable-backgrounding-occluded-windows --kiosk "$URL"

# Fallback auf andere Browser
if ! command -v chromium-browser >/dev/null 2>&1; then
    if command -v firefox >/dev/null 2>&1; then
        firefox --kiosk "$URL"
    elif command -v google-chrome >/dev/null 2>&1; then
        google-chrome --kiosk --no-sandbox "$URL"
    fi
fi

Desktop-Verknüpfung wird nicht angezeigt

Problem:

.desktop file created but not visible
Icon not displayed

Lösung:

# Desktop-Datei ausführbar machen
chmod +x ~/Desktop/myp-kiosk.desktop

# Icon kopieren
sudo cp backend/static/mercedes.svg /usr/share/pixmaps/myp-mercedes.svg
sudo chmod 644 /usr/share/pixmaps/myp-mercedes.svg

# Desktop-Datenbank aktualisieren
update-desktop-database ~/.local/share/applications/
xdg-desktop-menu forceupdate

# Gnome: Trusted Application markieren
dconf write /org/gnome/desktop/interface/enable-animations false

📊 Datenbank- und Persistenzfehler

SQLite-Datenbank Berechtigungsfehler

Problem:

sqlite3.OperationalError: attempt to write a readonly database
PermissionError: [Errno 13] Permission denied: 'instance/myp.db'

Lösung:

# Verzeichnis und Datei-Berechtigungen korrigieren
sudo chown -R $USER:$USER /opt/myp/instance/
chmod 755 /opt/myp/instance/
chmod 644 /opt/myp/instance/*.db

# Backup-Verzeichnis mit Schreibrechten
mkdir -p /opt/myp/instance/backups
chmod 755 /opt/myp/instance/backups

Backup-Prozess schlägt fehl

Problem:

rsync: command not found
tar: cannot create backup
disk full

Lösung:

# Notwendige Tools installieren
sudo apt install -y rsync tar gzip

# Speicherplatz prüfen
df -h /opt/myp/

# Alte Backups aufräumen (älter als 30 Tage)
find /opt/myp/instance/backups -name "*.tar.gz" -mtime +30 -delete

# Komprimierte Backups
tar -czf backup_$(date +%Y%m%d_%H%M%S).tar.gz instance/

🔐 Sicherheits- und Authentifizierungsfehler

JWT-Token-Validierung schlägt fehl

Problem:

jwt.DecodeError: Invalid token
SECRET_KEY not set

Lösung:

# In config.py sicherstellen:
import secrets
SECRET_KEY = secrets.token_urlsafe(32)

# Oder aus Umgebungsvariable:
SECRET_KEY = os.environ.get('SECRET_KEY') or secrets.token_urlsafe(32)

# Token-Expiration prüfen:
JWT_ACCESS_TOKEN_EXPIRES = timedelta(hours=24)

SSL Browser-Kompatibilitätsfehler (ERR_SSL_KEY_USAGE_INCOMPATIBLE)

Problem:

ERR_SSL_KEY_USAGE_INCOMPATIBLE
This site can't provide a secure connection
SSL certificate key usage incompatible

🚀 SUPER-SKRIPT LÖSUNG (Intelligente Komplettlösung):

# Das EINZIGE Super-Skript für ALLE Probleme:
cd /opt/myp
sudo ./setup_https_only.sh

# Das intelligente Super-Skript macht automatisch:
# ✅ ERR_SSL_KEY_USAGE_INCOMPATIBLE beheben
# ✅ Browser-kompatible SSL-Zertifikate erstellen
# ✅ Port 5000 blockieren, nur Port 443 öffnen
# ✅ SSL-Zertifikat-Gesundheit prüfen und erneuern
# ✅ Alle SSL-Probleme automatisch reparieren
# ✅ Connection refused beheben
# ✅ Graphical session target beheben
# ✅ Service-Dependencies reparieren
# ✅ Port-Konflikte lösen
# ✅ Kiosk intelligent konfigurieren
# ✅ Firewall für maximale Sicherheit

Lösung:

🍓 RASPBERRY PI (Zielsystem) - PRIMÄRE LÖSUNG:

# SSL-Fix auf Raspberry Pi ausführen
ssh pi@m040tbaraspi001
sudo chmod +x /tmp/fix_ssl_raspberry.sh
sudo /tmp/fix_ssl_raspberry.sh

# Oder via Setup-Skript
cd /opt/myp
sudo ./setup.sh  # Option [1] wählen

🔧 Alternative Tools:

# Cross-Platform Python Tool
cd backend
python3 ssl_fix.py

# Oder manuell neue browser-kompatible Zertifikate generieren:
cd backend/ssl
openssl genrsa -out key.pem 2048

# Erstelle OpenSSL-Konfiguration mit korrekten Extensions
cat > ssl_fix.conf << 'EOF'
[req]
distinguished_name = req_distinguished_name
req_extensions = v3_req
prompt = no

[req_distinguished_name]
C = DE
ST = Baden-Wuerttemberg
L = Stuttgart
O = Mercedes-Benz AG
OU = MYP Druckerverwaltung
CN = m040tbaraspi001

[v3_req]
basicConstraints = critical, CA:FALSE
keyUsage = critical, digitalSignature, keyEncipherment, keyAgreement
extendedKeyUsage = critical, serverAuth, clientAuth
subjectAltName = critical, @alt_names
nsCertType = server

[alt_names]
DNS.1 = localhost
DNS.2 = m040tbaraspi001
DNS.3 = m040tbaraspi001.de040.corpintra.net
IP.1 = 127.0.0.1
EOF

# Generiere browser-kompatibles Zertifikat
openssl req -new -x509 -key key.pem -out cert.pem -days 365 \
    -config ssl_fix.conf -extensions v3_req -sha256

# Validiere Extensions
openssl x509 -in cert.pem -noout -text | grep -A5 "Key Usage"

# Danach: Browser-Cache leeren und MYP neu starten

HTTPS-Redirect-Loop

Problem:

ERR_TOO_MANY_REDIRECTS
Infinite redirect between http and https

Lösung:

# In Flask-App prüfen:
from flask_talisman import Talisman

# Nur HTTPS forcieren wenn Zertifikat verfügbar
if os.path.exists('/opt/myp/ssl/cert.pem'):
    Talisman(app, force_https=True)
else:
    # Development: HTTP erlauben
    Talisman(app, force_https=False)

📝 Log-Dateien zur Fehlerdiagnose

Wichtige Log-Standorte:

# MYP Application Logs
/opt/myp/logs/app/app.log
/opt/myp/logs/errors/error.log

# Systemd Service Logs
journalctl -u myp-app.service -f
journalctl -u myp-kiosk.service -f

# System-Logs
/var/log/syslog
/var/log/nginx/error.log  # Falls Nginx verwendet wird

Log-Analyse-Befehle:

# Letzte 50 Fehler
tail -50 /opt/myp/logs/errors/error.log | grep ERROR

# Live-Monitoring
tail -f /opt/myp/logs/app/app.log

# Fehler der letzten Stunde
journalctl -u myp-app.service --since "1 hour ago" | grep ERROR

🛠️ Debugging-Tools

System-Informationen sammeln:

# System-Overview
uname -a
lsb_release -a
python3 --version
pip3 list | grep -E "(Flask|requests)"

# Netzwerk-Status
ip addr show
ss -tulpn | grep :443
curl -I http://localhost:5000/health

# Prozess-Status
ps aux | grep -E "(python|myp)"
systemctl status myp-*

Performance-Monitoring:

# CPU und Memory
top -p $(pgrep -f "python.*myp")
htop

# Disk I/O
iotop
df -h /opt/myp/

# Network
iftop
netstat -i

📋 Vorbeugende Maßnahmen

Regelmäßige Wartung:

# System-Updates
sudo apt update && sudo apt upgrade -y

# Python-Pakete aktualisieren
pip3 list --outdated
python3 -m pip install --upgrade pip

# Log-Rotation einrichten
sudo logrotate -f /etc/logrotate.conf

# Disk-Cleanup
sudo apt autoremove -y
sudo apt autoclean

Monitoring-Setup:

# Cron-Job für Health-Check (alle 5 Minuten)
echo "*/5 * * * * curl -f http://localhost:5000/health || systemctl restart myp-app.service" | crontab -

# Log-Size monitoring
echo "0 2 * * * find /opt/myp/logs -name '*.log' -size +100M -exec truncate -s 50M {} \;" | crontab -

---

💡 Tipp: Vor jeder größeren Änderung ein vollständiges Backup erstellen:

sudo tar -czf /tmp/myp_backup_$(date +%Y%m%d_%H%M%S).tar.gz /opt/myp/

Connection Refused (Kiosk-Modus)

Problem:

Connection refused
ERR_CONNECTION_REFUSED
Kiosk startet aber kann sich nicht mit MYP-Server verbinden

Ursachen:

• MYP-Server läuft nicht (myp-https/myp-app Service)
• Ports 443/5000 sind blockiert oder nicht belegt
• SSL-Zertifikate fehlen oder sind ungültig
• Python-Module fehlen oder sind defekt
• Firewall blockiert Verbindungen

🚀 Schnelle Lösung:

# Super-Skript ausführen (INTELLIGENTE Komplettlösung):
cd /opt/myp
sudo ./setup_https_only.sh

# Das Super-Skript erkennt und repariert automatisch:
# ✅ Connection refused Probleme
# ✅ Service-Status prüfen und reparieren
# ✅ Python-Module reparieren
# ✅ Port-Konflikte lösen
# ✅ SSL-Zertifikate validieren

🔍 Manuelle Diagnose (falls nötig):

# Service-Logs prüfen
journalctl -u myp-production -f
journalctl -u myp-https -f
journalctl -u myp-app -f

# Port-Status prüfen
netstat -tulpn | grep -E ':(443|5000|80)'

🔧 Manuelle Reparatur:

# 1. Services stoppen und neu starten
sudo systemctl stop myp-kiosk myp-https myp-app
sudo systemctl start myp-app myp-https myp-kiosk

# 2. Firewall-Ports öffnen
sudo ufw allow 443
sudo ufw allow 5000
sudo ufw allow 80

# 3. SSL-Zertifikate regenerieren
cd /opt/myp
sudo ./fix_ssl_raspberry.sh

# 4. Python-Module neu installieren
cd /opt/myp
sudo python3 -m pip install -r requirements.txt --break-system-packages --force-reinstall

# 5. App manuell testen
cd /opt/myp
python3 app.py

🎯 Verbindungstest:

# Teste lokale Verbindungen
curl -k https://localhost:443
curl http://localhost:5000
curl -k https://m040tbaraspi001.de040.corpintra.net

# Teste von anderem System
curl -k https://192.168.1.XXX:443

📋 Häufige Lösungen:

• Service läuft nicht: sudo systemctl enable --now myp-https
• Port blockiert: sudo ufw allow 443 && sudo ufw allow 5000
• SSL-Fehler: sudo ./fix_ssl_raspberry.sh
• Python-Fehler: sudo python3 -m pip install flask --break-system-packages
• Kiosk-URL falsch: Prüfe /etc/systemd/system/myp-kiosk.service

---

📞 Support: Bei ungelösten Problemen alle relevanten Logs und die Ausgabe der Debugging-Tools sammeln.