Troubleshooting

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 writable. init-dirs runs as root and hands /data/postgres to the postgres user.

• Missing required env vars — AUTH_SECRET, DATABASE_URL, MINIO_ROOT_USER/MINIO_ROOT_PASSWORD or S3_ACCESS_KEY/S3_SECRET_KEY not set. Typical log lines are AUTH_SECRET fehlt or MINIO_ROOT_PASSWORD fehlt.

First-run wizard not appearing

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

Causes:

• Wizard already completed — The wizard was already finished on this volume (SiteSettings.setupCompleted). After that, /setup redirects to the home page. To reset: stop the container, delete or replace the volume, and restart.

• API not reachable yet — Right after start the middleware cannot fetch setup.status from the API and shows the normal page instead of redirecting. Wait a few seconds and open /setup directly.

Videos stuck in processing

Symptom: A video stays in PENDING or PROCESSING status and never becomes LIVE.

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.

There is no admin function to re-queue a job, and there is no uploading status. Failed videos end up as FAILED with the error text in failureReason.

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. The default is 8192 (8 GB). Lower values take effect directly, higher values are capped by the internal Nginx of the AIO container, which is fixed at client_max_body_size 8g.
3. Restart the container so the API reads the new value. Nginx is not reconfigured from it.

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.
• Event stream not connected — Live updates use Server-Sent Events on /api/theme/events. If the connection dropped or a reverse proxy buffers the stream, reload the page to re-establish it and re-fetch the current theme.
• Custom CSS rejected or broken — Saves containing forbidden constructs (@import, expression(), </style> and others) are rejected with an error. There is no syntax check, so broken CSS is saved and simply has no effect.

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:

• S3 URL is wrong — The player loads HLS from NEXT_PUBLIC_S3_PUBLIC_URL / S3_PUBLIC_URL (in the browser from <origin>/s3). If these point to an unreachable host, the segment requests fail. Fix: in the all-in-one container keep both values at /s3, set PUBLIC_URL to the exact public URL (e.g. https://play.example.com), then restart the container.

• HLS CORS errors — The repo contains no MinIO CORS configuration. In the all-in-one container the browser loads everything same-origin via /s3/, so CORS only matters if MinIO is served under its own domain.

• No signed URLs — HLS files are served unsigned from the public-read bucket play-videos, so expiring URLs are not a cause.

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

Prisma Studio inside the container is not reachable from outside (port 5555 is not published), so use psql and change the role field with the SQL below.

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; trim no longer works for that video afterwards)
• Deleting videos in the admin panel only removes the DB record, the MinIO objects stay and have to be cleaned up separately
• 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/packages/db && pnpm exec prisma migrate status --schema prisma/schema.prisma"

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/packages/db && pnpm exec prisma migrate reset --force --schema prisma/schema.prisma"

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

docker exec -u postgres itsweber-play pg_dump -Fc itsweber_play > backup-$(date +%F).dump

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