Troubleshooting

🇩🇪 Deutsche Version

Common issues and how to resolve them. Start with the container logs in all cases:

docker logs itsweber-play

Container won't start

Symptom: Container exits immediately or stays in a restart loop.

Common causes and fixes:

• Port 3000 already in use — Another process or container is bound to port 3000.

  # Find what's using port 3000
  lsof -i :3000        # macOS / Linux
  netstat -ano | findstr :3000  # Windows

  Either stop the conflicting process or map ITSWEBER Play to a different host port (e.g. -p 8080:3000).

• Data volume permission error — The /data directory inside the container is not writable. Check that the volume or bind-mount path is accessible by the container user (UID 1000).

• Missing required env vars — BASE_URL or INITIAL_ADMIN_EMAIL not set. Check the logs for Missing required environment variable.

First-run wizard not appearing

Symptom: Navigating to the instance shows the normal interface instead of the setup wizard.

Causes:

• Data volume already initialized — The /data volume contains a previous installation. The wizard only shows once, on first boot with an empty data directory. To reset: stop the container, delete or replace the volume, and restart.

• BASE_URL mismatch — The browser URL does not match BASE_URL. The wizard redirect uses BASE_URL. If you're accessing via localhost but BASE_URL is set to a domain name, you'll be redirected away from the wizard.

Videos stuck in processing

Symptom: A video stays in processing or transcoding status and never becomes ready.

Fix:

docker logs itsweber-play | grep worker


docker logs itsweber-play | grep -i "transcode\|ffmpeg\|probe"

Common causes:

• FFmpeg crashed — Source file may be corrupted or in an unsupported container format. Check for ffmpeg: error lines in the output.
• Disk full — The worker has no space to write HLS segments. See Out of disk space.
• Worker process died — If the s6 supervisor didn't restart it, restart the container. BullMQ jobs are persistent and will resume.

To manually re-queue a stuck video, use Prisma Studio to set the video's status back to uploading and restart the container.

Upload fails immediately

Symptom: The upload progress bar appears but the upload fails within seconds, often with a 413 error.

Cause: The file size exceeds the configured limit.

Fix:

1. Check the current limit:

   docker inspect itsweber-play | grep MAX_UPLOAD_SIZE_MB

2. Increase it by setting MAX_UPLOAD_SIZE_MB to a higher value (e.g. 10240 for 10 GB).
3. Restart the container — the new value is applied to Nginx's client_max_body_size on start.

If you are running ITSWEBER Play behind an additional reverse proxy (Traefik, Caddy, external Nginx), that proxy's own body size limit may also need to be raised.

Can't log in after fresh install

Symptom: You registered an account but cannot access admin, or get a 403 after login.

Cause: The account was not auto-promoted to Admin because INITIAL_ADMIN_EMAIL was not set, or the registered email does not exactly match the value (check for typos, trailing spaces).

Fix:

1. Verify the env var is set correctly:

   docker inspect itsweber-play | grep INITIAL_ADMIN_EMAIL

2. If the var is correct but the account was already created before it was set, promote manually via Prisma Studio or a direct DB query:

   UPDATE "User" SET role = 'admin' WHERE email = 'you@example.com';

Theme changes not appearing

Symptom: You saved a theme change in the admin panel but the site still shows the old colors.

Causes and fixes:

• Browser cache — The most common cause. Hard refresh: Ctrl + Shift + R (Windows/Linux) or Cmd + Shift + R (macOS). Or open DevTools → Network → check "Disable cache", then reload.
• WebSocket not connected — Live updates require an active WebSocket connection. If the connection dropped, reload the page to re-establish it and re-fetch the current theme.
• Custom CSS syntax error — If a custom CSS save failed silently, the override may not have been applied. Check /admin/theme for any error banners.

Video playback issues

Symptom: Videos don't play, or play on the instance but not when shared — HLS errors in the browser console.

Common causes:

• BASE_URL is wrong — Signed playback URLs are generated using BASE_URL. If it is set to localhost in production, or to a different domain than the browser is using, the HLS requests will point to the wrong host and fail with CORS or 403 errors. Fix: Set BASE_URL to the exact public URL (e.g. https://play.example.com), then restart the container.

• HLS CORS errors — MinIO's CORS policy is set to allow requests from BASE_URL only. If you access the instance from a different origin (e.g. during local dev with a port mismatch), the browser will block the segment requests.

• Signed URL expired — For private and logged_in videos, signed URLs expire after 1 hour. Reloading the video page generates a fresh URL.

Admin promoted wrong user

Symptom: You accidentally gave Admin or Moderator role to the wrong account.

Fix via admin panel:

1. Go to /admin/users
2. Find the user by email
3. Click their role badge and select Viewer (or the correct role) to demote them

Fix via Prisma Studio (if locked out of admin):

docker exec -it itsweber-play sh -c "cd /app && npx prisma studio"

Open the User table, find the account, and change the role field.

Fix via direct SQL:

UPDATE "User" SET role = 'viewer' WHERE email = 'wrong@example.com';

Out of disk space

Symptom: Uploads fail, transcoding stops mid-way, or the container crashes with I/O errors.

Check current usage:

docker exec itsweber-play df -h /data


docker exec itsweber-play du -sh /data/minio/*

Free up space:

• Delete unused source files in play-raw/ (original uploads are retained post-transcode by default)
• Delete videos in the admin panel — this removes MinIO objects as well as the DB record
• Archive old HLS segments to external storage

To change the data directory location on Unraid, edit the container's Volume mapping in the Docker tab and point it to a larger share.

Database migration errors

Symptom: Container logs show Migration failed or the API fails to start with a Prisma error.

Check migration status:

docker exec itsweber-play sh -c "cd /app && npx prisma migrate status"

Common fixes:

• Pending migrations — If you updated the container image and the DB is behind: the container's init sequence runs prisma migrate deploy automatically on start. If it failed, check the logs for the specific SQL error.

• Drift detected — If the database schema differs from the migration history (e.g. from a manual SQL change): resolve the drift before applying new migrations. Do not use prisma migrate reset in production — it deletes all data.

• Manual reset (development only):

  # WARNING: destroys all data in the database
  docker exec itsweber-play sh -c "cd /app && npx prisma migrate reset --force"

If you are unsure, take a database backup before attempting any migration recovery steps:

docker exec itsweber-play pg_dump -U play play > backup-$(date +%Y%m%d).sql

Still stuck?

• Check the full logs: docker logs itsweber-play 2>&1 | tail -200
• Open an issue on GitHub: github.com/ITSWEBER-OFFICIAL/itsweber-play/issues

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