Fehlerbehebung

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: Die API war beim Aufruf noch nicht erreichbar, etwa kurz nach dem Start. Die Middleware leitet dann nicht um, sondern zeigt die normale Seite. Ein paar Sekunden warten und /setup direkt aufrufen.

Ursache B: Der Assistent wurde auf diesem Datenvolume bereits abgeschlossen (SiteSettings.setupCompleted). Danach leitet /setup auf die Startseite zurück.

Lösung:

docker exec -it itsweber-play psql -U play -d itsweber_play -c "SELECT email, role FROM \"User\" 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 ZCARD bull:transcode:failed

Eine Funktion zum erneuten Einreihen fehlgeschlagener Jobs gibt es im Admin-Panel nicht. Fehlgeschlagene Videos stehen mit Status FAILED und Fehlertext in failureReason in der Datenbank.

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 (Standard 8192). Die API antwortet dann mit 413 PAYLOAD_TOO_LARGE.

Ursache B: Ein vorgeschalteter Reverse Proxy (Nginx, Traefik) blockiert die Anfrage wegen client_max_body_size. Im AIO-Container begrenzt zusätzlich der interne Nginx fest auf 8 GB, ein höherer MAX_UPLOAD_SIZE_MB wirkt dort nicht.

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 itsweber_play -c "SELECT email, role FROM \"User\";"


docker exec -it itsweber-play psql -U play -d itsweber_play -c \
  "UPDATE \"User\" 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, die Server-Sent-Events-Verbindung zu /api/theme/events im Browser prüfen (DevTools → Network). Puffert ein Reverse Proxy die Antwort, kommen die Events nicht an

docker exec -it itsweber-play psql -U play -d itsweber_play -c \
  "SELECT \"tokensOverride\" FROM \"ThemeSettings\" LIMIT 1;"

Video-Wiedergabe-Probleme

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

Ursache A: NEXT_PUBLIC_S3_PUBLIC_URL oder S3_PUBLIC_URL zeigen auf einen nicht erreichbaren Host. Im AIO-Container sollten beide /s3 sein.

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

Lösung:

docker exec itsweber-play printenv PUBLIC_URL S3_PUBLIC_URL NEXT_PUBLIC_S3_PUBLIC_URL


curl -I "https://play.example.com/s3/play-videos/[videoId]/master.m3u8"

Sicherstellen, dass PUBLIC_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 itsweber_play -c \
  "UPDATE \"User\" SET role = 'VIEWER' WHERE email = 'falsch@example.com';"


docker exec -it itsweber-play psql -U play -d itsweber_play -c \
  "UPDATE \"User\" 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 du -sh /data/minio/*


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

Rohvideos unter play-raw/ braucht Play für die Wiedergabe nicht mehr. Trim greift aber auf das Original zurück und funktioniert nach dem Löschen für das betroffene Video nicht mehr. Das Löschen eines Videos im Admin-Panel entfernt übrigens nur den Datensatz, die Dateien in MinIO bleiben liegen.

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 itsweber_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 itsweber_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 s6-svstat /run/service/api
docker exec itsweber-play s6-svstat /run/service/worker
docker exec itsweber-play s6-svstat /run/service/web


docker stats itsweber-play --no-stream