Troubleshooting

Passwort und MFA prüfen
HEADLESS=false in .env setzen → sichtbares Chromium beim nächsten Scrape, du siehst direkt was schiefgeht

`Executable doesn't exist` (Playwright)

npx playwright install chromium

Im Docker-Image ist Chromium bereits dabei — dieser Fehler tritt nur bei lokaler Installation auf.

Scraper hängt minutenlang

WISS / Tocco-Portal kann gerade langsam sein
Setze DEBUG_SCRAPER=true → bei Fehlern werden DOM-Dumps in data/ geschrieben

Tocco-Portal hat sich geändert (HTML-Layout)

Selektoren in src/scraper.js und src/db/parsers.js brauchen Update. Issue mit DOM-Dump auf GitHub eröffnen.

API & Auth

Token vergessen

rm data/.api-token
# Restart → neuer Token in den Logs
docker logs tocco-mate | grep AUTO-GENERATED

`401 Unauthorized` trotz Token

Header-Format prüfen: Authorization: Bearer <token> (mit Leerzeichen)
Token aus data/.api-token (komplette Zeile, ohne Whitespace)
Bei ?token= URL-Param: nur auf /api/events erlaubt

`429 Too Many Requests`

Anti-Brute-Force greift. Warte 15 Minuten oder restarte den Container. Siehe Sicherheit.

Mobile / PWA / Push

Mobile-Push aktivieren geht nicht

Mobile-Push braucht HTTPS. Über LAN-IP funktioniert’s nicht (Browser-Sicherheitsregel). Lösung: Reverse-Proxy mit TLS davor — siehe Sicherheit.

iOS Push-Toggle ausgegraut

Die PWA muss installiert sein (Safari → Teilen → „Zum Home-Bildschirm”), nicht im Browser-Tab.

Brave-Push schlägt fehl

brave://settings/privacy → „Google-Dienste für Push-Nachrichten verwenden” aktivieren. Brave blockt Google-FCM standardmäßig.

Service-Worker-Updates kommen nicht durch

Hard-Refresh (Ctrl+Shift+R / Cmd+Shift+R) oder PWA deinstallieren + neu installieren.

Daten & DB

Stundenplan zeigt alte Einträge

Im Stundenplan-Tab → „DB zurücksetzen” → manueller Scrape. Die Tabelle wird komplett neu aufgebaut.

Wochen-Check soll erneut laufen

rm data/.weekly-detail-at
# Restart

Keine LB / ZP im Modul

Beim nächsten Scrape wird’s nachgezogen. Manuell: /scrape im Dashboard oder Telegram.

`database is locked`

Sehr selten — meist wenn zwei Container gleichzeitig auf dasselbe data/ zugreifen. Nur einen Container pro data/-Ordner laufen lassen.

DB-Backup während Container läuft

docker exec tocco-mate sh -c 'sqlite3 /app/data/tocco.db ".backup /tmp/tocco-backup.db"'
docker cp tocco-mate:/tmp/tocco-backup.db ./tocco-backup-$(date +%Y%m%d).db

Docker

`EACCES: permission denied` auf `/app/data`

PUID / PGID stimmen nicht. Siehe NAS / Unraid.

Container restartet ständig

docker logs tocco-mate

Häufigste Ursachen:

Health-Check schlägt fehl (Server brauchte > 30 s zum Boot) → start_period: 60s in compose
MS_EMAIL oder MS_PASSWORD fehlen → Logs zeigen Login-Error
Port 3000 schon belegt → Port mappen -p 3001:3000

Chromium-Sandbox-Error

Siehe Docker Deployment → Chromium-Sandbox.

Telegram-Bot

Bot reagiert nicht

TELEGRAM_ENABLED=true gesetzt?
TELEGRAM_TOKEN korrekt (vom BotFather, mit Doppelpunkt)?
TELEGRAM_ALLOWED_USER_ID ist deine ID (vom @userinfobot)?
Server neu gestartet nach .env-Änderung?

„Bot is unauthorized”

Token ist falsch oder Bot wurde im BotFather gelöscht. Neuen Token holen.

Bot reagiert auf `/start`, aber sonst nicht

Du bist evtl. nicht der TELEGRAM_ALLOWED_USER_ID. Prüfe deine ID via @userinfobot.

Performance

Scrape dauert > 60 s

Tocco-Portal langsam — abwarten
HEADLESS=false + SLOW_MO=100 für Debug
DOM-Dumps via DEBUG_SCRAPER=true

Hohe CPU-Last während Idle

Scheduler-Intervall zu kurz. In Settings auf 30 min oder mehr stellen — die Scrapes brauchen keine 5-Minuten-Granularität.

Sonstiges

Wo logge ich Issues?

→ https://github.com/JoKerIsCraZy/tocco-mate/issues

Bitte vorher die offenen Issues durchsuchen — vielleicht gibt’s das Problem schon.