Fehlerbehebung

🇬🇧 English Version

Häufige Probleme und deren Lösungen. Alle Diagnose-Befehle beziehen sich auf den Standard-Containernamen itsweber-play.

Container startet nicht

Problem: docker start itsweber-play schlägt sofort fehl oder der Container beendet sich direkt nach dem Start.

Ursache: Häufigste Gründe sind ein belegter Port 3000, fehlende Pflicht-Umgebungsvariablen oder ein beschädigtes Datenvolume.

Lösung:

docker logs itsweber-play


lsof -i :3000


netstat -ano | findstr :3000


docker inspect itsweber-play | grep -A 20 '"Env"'

Einrichtungsassistent erscheint nicht

Problem: Beim ersten Aufruf von http://localhost:3000 wird statt des Einrichtungsassistenten eine leere Seite oder die normale Startseite angezeigt.

Ursache A: BASE_URL stimmt nicht mit der aufgerufenen URL überein (z. B. https:// vs. http://).

Ursache B: Das Datenvolume war bereits zuvor initialisiert — ein bestehendes Admin-Konto ist vorhanden.

Lösung:

docker exec -it itsweber-play psql -U play -d play -c "SELECT email, role FROM users WHERE role = 'admin';"


docker compose down -v
docker compose up -d

Videos bleiben bei "Wird verarbeitet"

Problem: Hochgeladene Videos stecken dauerhaft im Status "Wird verarbeitet" und erreichen nie den Status "Bereit".

Ursache: Der Worker-Prozess ist abgestürzt, hat einen fatalen Fehler geworfen oder FFmpeg ist nicht korrekt im Container verfügbar.

Lösung:

docker logs itsweber-play 2>&1 | grep -i worker


docker logs itsweber-play 2>&1 | grep -i "error\|fatal\|ffmpeg"


docker exec -it itsweber-play redis-cli LLEN bull:video-processing:failed

Wenn Jobs in der Failed-Queue landen, können sie im Admin-Panel unter /admin/videos erneut in die Warteschlange gestellt werden.

Upload schlägt sofort fehl

Problem: Beim Versuch, eine Datei hochzuladen, erscheint sofort eine Fehlermeldung — bevor der Upload überhaupt beginnt.

Ursache A: Die Datei überschreitet MAX_UPLOAD_SIZE_MB.

Ursache B: Ein vorgeschalteter Reverse Proxy (Nginx, Traefik) blockiert die Anfrage wegen client_max_body_size.

Lösung:

docker exec itsweber-play printenv MAX_UPLOAD_SIZE_MB

Für Traefik: --entrypoints.web.transport.respondingTimeouts.readTimeout und Body-Size-Limits in den Middlewares anpassen.

Kann nach Neuinstallation nicht anmelden

Problem: Nach einem frischen Setup schlägt die Anmeldung mit der Admin-E-Mail fehl oder der Nutzer erhält keine Admin-Rechte.

Ursache A: INITIAL_ADMIN_EMAIL wurde nicht gesetzt oder enthält einen Tippfehler.

Ursache B: Die registrierte E-Mail-Adresse weicht in Groß-/Kleinschreibung oder Leerzeichen vom Wert in INITIAL_ADMIN_EMAIL ab.

Lösung:

docker inspect itsweber-play | grep INITIAL_ADMIN_EMAIL


docker exec -it itsweber-play psql -U play -d play -c "SELECT email, role FROM users;"


docker exec -it itsweber-play psql -U play -d play -c \
  "UPDATE users SET role = 'admin' WHERE email = 'admin@example.com';"

Theme-Änderungen erscheinen nicht

Problem: Im Admin-Theme-Editor vorgenommene Änderungen sind im Browser nicht sichtbar.

Ursache: Browser-Cache hält alte CSS-Variablen.

Lösung:

1. Hard-Refresh durchführen: Strg + Umschalt + R (Windows/Linux) oder Cmd + Umschalt + R (macOS)
2. Browser-Cache für die Domain leeren
3. Falls das Problem weiterhin besteht: WebSocket-Verbindung im Browser prüfen (DevTools → Network → WS)

docker exec -it itsweber-play psql -U play -d play -c \
  "SELECT tokens_override FROM theme_settings LIMIT 1;"

Video-Wiedergabe-Probleme

Problem: Videos laden nicht, zeigen CORS-Fehler oder spielen auf dem falschen Host ab.

Ursache A: BASE_URL ist falsch gesetzt — signierte MinIO-URLs zeigen auf einen nicht erreichbaren Host.

Ursache B: HLS-CORS-Header sind für externe Domains nicht korrekt konfiguriert.

Lösung:

docker exec itsweber-play printenv BASE_URL


curl -I "https://play.example.com/api/video/[videoId]/stream"

Sicherstellen, dass BASE_URL exakt der öffentlichen URL entspricht, unter der der Container erreichbar ist — einschließlich Protokoll (https://) und ohne Trailing-Slash.

Falscher Benutzer als Admin

Problem: Ein Nutzer hat versehentlich Admin-Rechte erhalten oder die Admin-Rolle muss auf ein anderes Konto übertragen werden.

Lösung über Prisma Studio:

pnpm --filter @play/db exec prisma studio

Lösung über Datenbank-Direktabfrage:

docker exec -it itsweber-play psql -U play -d play -c \
  "UPDATE users SET role = 'viewer' WHERE email = 'falsch@example.com';"


docker exec -it itsweber-play psql -U play -d play -c \
  "UPDATE users SET role = 'admin' WHERE email = 'richtig@example.com';"

Kein Speicherplatz mehr

Problem: Container startet nicht oder Uploads schlagen fehl mit "no space left on device".

Ursache: Das MinIO-Datenverzeichnis oder der Docker-Volume-Speicher ist voll.

Lösung:

docker system df -v


docker exec -it itsweber-play mc du --recursive /data/minio/


docker exec -it itsweber-play mc ls /data/minio/play-raw/

Rohvideos unter play-raw/ können nach erfolgreicher Transcodierung gelöscht werden — sie werden für die HLS-Wiedergabe nicht mehr benötigt.

Datenbank-Migrationsfehler

Problem: Container startet mit Fehler migration failed oder database schema out of date.

Ursache: Eine Prisma-Migration konnte nicht angewendet werden — häufig nach einem manuellen Datenbankeingriff oder einem abgebrochenen Update.

Lösung:

docker exec -it itsweber-play psql -U play -d play -c \
  "SELECT migration_name, finished_at FROM _prisma_migrations ORDER BY finished_at DESC LIMIT 10;"


docker exec -it itsweber-play psql -U play -d play -c \
  "DELETE FROM _prisma_migrations WHERE migration_name = 'fehlgeschlagene_migration';"


docker restart itsweber-play

Warnung: Manuelles Eingreifen in die Migrationstabelle _prisma_migrations kann den Datenbankzustand inkonsistent machen. Vorher ein Backup erstellen.

Allgemeine Diagnose

docker logs --tail 100 itsweber-play


docker logs -f itsweber-play


docker exec itsweber-play cat /var/log/api/current
docker exec itsweber-play cat /var/log/worker/current
docker exec itsweber-play cat /var/log/web/current


docker stats itsweber-play --no-stream

© Benjamin Weber · ITSWEBER — play.itsweber.net · GitHub