Troubleshooting

When something breaks, start with container logs. Most issues show up there before the UI does.

Encoding stuck on "processing"

docker compose logs queue
docker compose exec queue supervisorctl status

Usually one of: queue worker down, Redis unreachable, missing bin/media-vod, full disk, or FFmpeg not in the queue container.

docker compose restart queue
# backlog?
docker compose up -d --scale queue=3

Whisper / transcription fails

docker compose exec queue /opt/whisper/whisper-cli --help
docker compose exec queue ls -la /opt/whisper/models/

Check WHISPER_CLI_PATH, that model files exist under WHISPER_MODELS_PATH, and the source actually has an audio track. Silent videos produce nothing useful.

Live streaming not working

OBS won't connect or the stream never shows as active.

docker compose logs nixstream-live
curl http://localhost:8888/health

Port 1935 must be open (firewall + cloud security group). MEDIA_SERVER_INGEST_IP should be the server's public IP on manual installs. Double-check the stream key from the panel. HEVC live is known-broken. Use H.264 in OBS.

Database connection errors

docker compose ps
docker compose exec db mysqladmin ping -h localhost
docker compose exec app php artisan tinker --execute="DB::connection()->getPdo();"

If nixstream_db isn't healthy, verify DB_* env vars match the Compose service names.

Admin login fails

After Docker install, install.sh prints a one-time admin password (not saved in .env). Email is ADMIN_EMAIL in .env (default [email protected]). To reset: ./scripts/create-admin.sh.

Also check migrations ran (php artisan migrate --seed), APP_URL matches what you type in the browser, and Redis is up. Sessions live there.

API returns 401

Send Authorization: Bearer YOUR_API_KEY. Key comes from Settings > General. Revoked keys fail silently from the client's perspective. Generate a fresh one if unsure.

Upload fails (413 / timeout)

Raise Nginx client_max_body_size (10G is common for video), PHP upload_max_filesize / post_max_size, and any reverse-proxy read timeout in front of the app.

Permission errors after ACL changes

php artisan permission:cache-reset

Run this after editing config/acl.php.